> For the complete documentation index, see [llms.txt](https://docs.testvibe.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.testvibe.com/create-tests/write-good-test-instructions.md). # 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.md#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.md). When the feature is ready, continue to [Generate Playwright code](/ai-generation/generate-playwright-code.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://docs.testvibe.com/create-tests/write-good-test-instructions.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.