# Write Good Test Instructions

URL: https://docs.testvibe.com/create-tests/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 | The landing entrypoint, reached first | `Given I am on the "Login" page` — then navigate forward with explicit steps | 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"` | A unique value for anything created | `And the user creates a project named "Project {{unique}}"` 

Visible details help the generated test find and verify the right UI. Every feature should reach its starting screen the same way a real user would — see [Always start at the entrypoint](/create-tests/gherkin-and-feature-files#always-start-at-the-entrypoint) — rather than assuming an already-signed-in or already-navigated state.

## 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
- wrap any value the test creates (an email, a record name) in `{{unique}}` so a repeat run doesn't collide with data the last run left behind
- 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) . When the feature is ready, continue to [Generate Playwright code](/ai-generation/generate-playwright-code) .