Write Good Test Instructions

Write clear Gherkin and test instructions that help TestVibe generate reliable Playwright code.

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:

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 — 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:

Scenario: Settings
  When I change settings
  Then it saves

Better:

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. When the feature is ready, continue to Generate Playwright code.