# Write good test instructions

Good instructions tell TestVibe what the user does and what visible result proves the behavior worked.

The goal is not to write implementation detail. The goal is to describe a repeatable user journey clearly enough for AI generation and human review.

## The Simple Formula

Use this pattern:

| Part  | Purpose                                     |
| ----- | ------------------------------------------- |
| Given | The starting context.                       |
| When  | The action the user takes.                  |
| Then  | The visible outcome TestVibe should verify. |

Example:

```gherkin
Scenario: User filters invoices by overdue status
  Given the user is on the invoices page
  When the user filters invoices by "Overdue"
  Then only overdue invoices should be shown
  And the overdue filter should remain selected
```

## What To Include

Strong instructions include:

| Include                   | Example                                             |
| ------------------------- | --------------------------------------------------- |
| Page or starting location | `Given the user is on the account settings page`    |
| Visible labels            | `When the user clicks "Save changes"`               |
| Input values              | `And the user enters "QA Team" as the team name`    |
| Expected message          | `Then a "Team created" message should appear`       |
| Expected navigation       | `Then the dashboard should open`                    |
| Stable test data          | `Given the account has an invoice named "INV-1001"` |

Visible details help the generated test find and verify the right UI.

## What To Avoid

Avoid instructions that are too vague:

| Weak                    | Better                                                                 |
| ----------------------- | ---------------------------------------------------------------------- |
| `When the user logs in` | `When the user enters a valid email and password and clicks "Sign in"` |
| `Then it should work`   | `Then the dashboard should open and the user's name should be visible` |
| `Check billing`         | `Then the billing page should show the current subscription plan`      |
| `Do the setup`          | `Given the user is signed in as an administrator`                      |

If a person could not tell what to verify, the generated test probably cannot either.

## Keep Scenarios Focused

One scenario should usually cover one behavior:

| Focused                            | Too broad                                                      |
| ---------------------------------- | -------------------------------------------------------------- |
| Reset password with a valid email. | Sign in, update profile, reset password, and download invoice. |
| Add one product to the cart.       | Browse, search, compare, checkout, and cancel order.           |

Split long flows into smaller features or use prerequisites when setup is shared.

## Write For Repeatability

Generated tests are easier to run when the scenario can repeat without manual cleanup.

Do:

* use test accounts
* use stable records or create records during setup
* describe how the test reaches the starting state
* avoid depending on today's date unless it is part of the behavior
* avoid relying on data that another user might change

## Good Before And After

Weak:

```gherkin
Scenario: Settings
  When I change settings
  Then it saves
```

Better:

```gherkin
Scenario: User updates notification preference
  Given the user is on the account settings page
  When the user turns on email notifications
  And the user clicks "Save"
  Then a "Settings saved" message should appear
  And email notifications should still be on after the page reloads
```

## Next

For the syntax behind these examples, see [Gherkin and feature files](/create-tests/gherkin-and-feature-files.md). When the feature is ready, continue to [Generate Playwright code](/ai-generation/generate-playwright-code.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.testvibe.com/create-tests/write-good-test-instructions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.