---
title: Projects and Tests
description: Create projects, write tests, attach environments, schedule checks, and manage defaults from the CLI.
---

# 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

```bash
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:

```bash
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

```bash
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:

```bash
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:

```bash
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.

```bash
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

```bash
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:

| Value | Meaning |
|---|---|
| `desktop` | Run with a desktop browser profile |
| `mobile` | Run with a mobile browser profile |
| `both` | Let Smoketest run the test across both supported targets |

`both` is the default.

## Attach an environment

```bash
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

```bash
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:

```bash
smoketest tests schedule "Homepage smoke test"
```

Set and enable a schedule:

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

Disable a schedule without deleting the test:

```bash
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:

```bash
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:

```bash
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.