Projects and Tests

Projects group reusable Tests, Runs, and environments. A reusable Test is an editable browser journey you describe in a sentence, with a start URL and expected outcome. Ticket-generated Tests are immutable Attempt artifacts and are not managed by these commands.

Create and use a project

smoketest projects create --name "Production" --url https://example.com --use

--use saves the project as the default for the active profile, so future commands can omit --project.

Common project commands:

smoketest projects list
smoketest projects get "Production"
smoketest projects edit "Production" --url https://www.example.com
smoketest projects use "Production"
smoketest projects delete "Production"

Destructive commands ask for confirmation by default. Use --yes in automation.

Create a test

smoketest tests create \
  --name "Homepage smoke test" \
  --url https://example.com \
  --description "Open the homepage, check the main CTA, and verify pricing is reachable"

When a default project is set, --project is optional. Without a default project, pass a project ID, short ID, or exact project name:

smoketest tests create \
  --project "Production" \
  --name "Signup smoke test" \
  --url https://example.com/signup \
  --description "Create an account and land on the onboarding checklist"

Write descriptions in files

Use @file for longer test descriptions:

smoketest tests create \
  --name "Checkout smoke test" \
  --url https://example.com \
  --description @tests/checkout.md

The CLI asks before reading sensitive-looking filenames such as .env, or names containing secret, token, credential, password, or api-key.

Create reusable Shared Steps

Shared Steps are named, project-scoped markdown snippets that can be inserted into test descriptions in the app. Type / on a blank line in the rich editor and choose a Shared Step by name; the test stores a stable Shared Step chip while runs expand the latest Shared Step description.

smoketest shared-steps create \
  --project "Production" \
  --name "Log in" \
  --description @tests/login.md

smoketest shared-steps list --project "Production"
smoketest shared-steps get "Log in" --project "Production"
smoketest shared-steps edit "Log in" --project "Production" --editor

Shared Steps can be resolved by full ID, short ID, or exact name. Deleting a Shared Step is blocked while any test references it.

Device target

smoketest tests create \
  --name "Mobile signup" \
  --url https://example.com \
  --description "Open signup, create an account, and see the welcome page" \
  --device mobile

Supported device values are:

both is the default.

Attach an environment

smoketest tests create \
  --name "Authenticated dashboard" \
  --url https://example.com/login \
  --description @tests/login.md \
  --env staging

--env accepts an environment ID, short ID, or exact environment name in the selected project.

Edit tests

smoketest tests edit "Homepage smoke test" --name "Homepage and pricing"
smoketest tests edit "Homepage and pricing" --description @tests/homepage.md
smoketest tests edit "Homepage and pricing" --editor

--editor opens the full test payload as JSON in your editor.

Schedule tests

Inspect the current schedule and available presets:

smoketest tests schedule "Homepage smoke test"

Set and enable a schedule:

smoketest tests schedule "Homepage smoke test" --schedule daily-9 --enable

Disable a schedule without deleting the test:

smoketest tests schedule "Homepage smoke test" --disable

Schedules use Smoketest's supported presets rather than arbitrary cron strings.

IDs and names

Tables show short 8-character IDs. Commands accept:

• Full UUIDs
• Short IDs, when they match exactly one resource
• Exact names, when a command supports name resolution

Examples:

smoketest projects get 4fa56a33
smoketest tests run "Homepage smoke test" --watch
smoketest tests run "Homepage smoke test" --url https://preview-acme.vercel.app

If a short ID matches more than one resource, the CLI fails and asks for a longer identifier.

Run tests by tag

Tags are managed in the Smoketest app. After assigning tags to tests, the CLI can filter and run groups inside the selected project:

smoketest tests list --project "Production" --tag Smoke
smoketest tests run --project "Production" --tag Smoke
smoketest tests run --project "Production" --tag Smoke --url https://staging.acme.com

If a default project is set with smoketest projects use, --project can be omitted. --watch is not supported with --tag; use smoketest runs watch <run> for an individual run from the group. Pass --url to run the group against one preview or staging URL without editing saved tests.