> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qlane.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Test cases

> Write plain-English test cases for the QLane agent — draft, active, and archived states, AI-drafted proposals from PR diffs, levels, tags, and versioning.

A **test case** describes a behaviour you want QLane to verify. It's written in plain English, not code. You don't write selectors or assertions — the agent figures out how to perform the steps against the running app.

## Lifecycle: draft → active → archived

Test cases move through three states:

* **Draft.** Either AI-drafted from a PR diff or hand-written. Drafts are visible but don't run as part of normal sessions.
* **Active.** Runs on every applicable session.
* **Archived.** Hidden from new sessions. Past sessions still show their result.

The transition from `draft` to `active` is always a human action. **Drafts only become active when you accept them** — usually by clicking "Accept" on the proposal, or by merging the PR that introduced them.

## How drafts get generated

QLane drafts test cases in two situations:

* **From every PR diff.** When a PR is opened, QLane reads the diff and proposes test cases for the new behaviour. Drafts show up in the project's **Test cases** tab marked with the PR they came from.
* **From a baseline exploration.** On first project setup (and on demand), the agent explores your app and proposes a smoke suite — *"sign in works"*, *"create a project works"*, *"invite a teammate works"*. These show up the same way.

Drafts that don't get accepted simply expire — they never enter your active suite.

## Writing a test case yourself

Open the **Test cases** tab and click **New test case**.

1. **Title** — a one-liner.
2. **Goal** — what should happen, from the user's point of view. Example: *"A signed-in user can create a project and see it in the project list."*
3. **Preconditions** *(optional)* — state the app must be in before the test (a known fixture, a test account, etc.).
4. **Level** — `smoke` (must always pass), `sanity`, or `regression`.
5. **Tags** — for filtering and selective runs.

You're done. The next session picks it up.

## Test levels

Levels signal what *kind* of failure each test catches:

* **Smoke** — the app is alive. If smoke fails, nothing else matters. Smoke is what runs first and what gates merges.
* **Sanity** — primary user flows. Most of your active suite lives here.
* **Regression** — narrow tests pinned to specific past bugs. They guard against re-introductions.

QLane infers a level when drafting, but you can override.

## Editing and versioning

Editing a test case applies to all future runs. **Past session reports show the version of the test case that was in effect at the time**, so historical results remain reproducible.

## Writing tests the agent runs well

A few patterns work well:

* **One outcome per case.** "Sign in *and* create a project" should be two cases — failures are easier to diagnose.
* **Describe the user's intent, not the UI.** "Sign in" beats "Click the green button labelled 'Sign in'" — the latter breaks the moment you rename the button.
* **Reference real fixtures.** "Sign in as `qa@example.com`" is more reliable than "Sign in as a test user."
* **Lean on preconditions.** Don't make the test create its own scaffolding if a precondition can pin it.

## Promotions and demotions

Accepted test cases aren't immutable. The agent watches how each one performs across sessions and surfaces proposals:

* **Promote** a frequently-passing sanity test to smoke, if it covers a critical path.
* **Demote** a frequently-flaky case to regression so it doesn't gate merges.
* **Archive** a case that's been duplicated by a newer one.

You approve or reject each proposal — promotions and demotions are never silent.