> 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/readme/key-concepts.md).

# Key Concepts

This page explains the main TestVibe terms you will see while setting up a project, creating tests, generating Playwright code, running tests, and reviewing results.

You do not need to memorize every term before using TestVibe. Use this page as a map when a screen, setting, or result mentions something new.

## The Big Picture

TestVibe connects a few important pieces:

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Project</strong></td><td>The place where your team works on one app — its site URLs, tests, runs, and evidence.</td><td><a href="/pages/AMnU2pTMCri7pum7FEH4">/pages/AMnU2pTMCri7pum7FEH4</a></td></tr><tr><td><strong>Test Suite</strong></td><td>The organized list of groups and tests that describe what your application should do.</td><td><a href="/pages/KFyP2bFH4rdoYqFMEwha">/pages/KFyP2bFH4rdoYqFMEwha</a></td></tr><tr><td><strong>AI generation</strong></td><td>The process that turns test intent into generated Playwright code saved to your project.</td><td><a href="/pages/W3i7XJVOFjRvYAOMTe50">/pages/W3i7XJVOFjRvYAOMTe50</a></td></tr><tr><td><strong>Cloud test session</strong></td><td>The isolated cloud sandbox that executes generation and Playwright test runs.</td><td><a href="/pages/N0ItykoTf2IYKz9TZQSp">/pages/N0ItykoTf2IYKz9TZQSp</a></td></tr><tr><td><strong>Run</strong></td><td>An execution of one test, a group, or the full suite against a target site.</td><td><a href="/pages/jRDweXS74GF5RysL7hCO">/pages/jRDweXS74GF5RysL7hCO</a></td></tr><tr><td><strong>Result evidence</strong></td><td>The screenshots, videos, traces, console output, and network details that help explain what happened.</td><td><a href="/pages/8ZXQNue5oXlx0RsH5wHp">/pages/8ZXQNue5oXlx0RsH5wHp</a></td></tr></tbody></table>

## Workspace Concepts

These terms appear when you sign in and set up where you work.

| Term                   | What it means                                                                                                                                                                                                                                           |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| You                    | The person who signs in. Sign in with email/password, GitHub, or Google — sign-in is identity-only. Your personal settings live in Settings → Profile.                                                                                                  |
| Workspace              | The container that owns projects, billing, credits, plan, and storage. Every user gets a personal workspace, and you can create team workspaces to share with others. Switch the active workspace from the header switcher.                             |
| Member                 | A person in a workspace, with the Owner, Admin, Member, or Viewer role. Members are invited from Settings → Members (personal workspaces have no other members).                                                                                        |
| Project                | One app under test: a name, the site URL(s) to test, and all of its tests, runs, and evidence.                                                                                                                                                          |
| Site URL               | The web application address your tests run against. A project can have more than one.                                                                                                                                                                   |
| Source code connection | An optional, read-only repository the assistant reads to understand your app's code, set up in Settings → App Repository — separate from Settings → Test Files Sync, which mirrors your generated test files (GitHub, GitLab, or Azure DevOps) two-way. |
| Project settings       | The settings that affect generation, runs, AI model, and configurations.                                                                                                                                                                                |
| Variables & secrets    | Values referenced from tests as `{{var:NAME}}` or `{{secret:NAME}}`, managed in Settings → Variables & Secrets.                                                                                                                                         |

For setup help, see [Set Up Your Workspace](/workspace.md).

## Test Suite Concepts

The Test Suite is where users organize test intent before generating or running tests.

| Term              | What it means                                                                                      |
| ----------------- | -------------------------------------------------------------------------------------------------- |
| Test Suite        | The organized collection of tests for the selected project.                                        |
| Group             | A folder-like section of the suite, often used for a feature area or user journey.                 |
| Gherkin           | The structured plain-language format TestVibe uses to describe feature behavior before generation. |
| Feature file      | A `.feature` file that describes one product capability or journey using Gherkin.                  |
| Test              | A specific behavior or scenario you want to validate.                                              |
| Feature           | A user-facing capability or flow that can contain one or more scenarios.                           |
| Scenario          | A concrete example of behavior to test, usually made of steps and expected outcomes.               |
| Background        | Shared setup that applies before each scenario in a feature file.                                  |
| Step              | A clear action or assertion, such as clicking a button or verifying a message appears.             |
| Given, When, Then | Gherkin keywords for context, action, and expected outcome.                                        |
| Scenario Outline  | A reusable scenario pattern that runs with different example values.                               |
| Prerequisite      | A test or setup flow that should happen before another test.                                       |
| Dependency        | A relationship where one test relies on another test or setup path.                                |
| Test instructions | The plain-language description TestVibe uses to understand what should be tested.                  |

Good tests start with clear intent. See [Gherkin and feature files](/create-tests/gherkin-and-feature-files.md) and [Write good test instructions](/create-tests/write-good-test-instructions.md).

## AI Generation Concepts

Generation is how TestVibe turns readable test intent into runnable Playwright code.

| Term                      | What it means                                                                                                                                         |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| AI generation             | The process of asking an AI agent to create or update test output from your instructions. Generation runs as a cloud agent and is metered in credits. |
| Generated Playwright code | The test file produced from your test intent, saved to your project.                                                                                  |
| Agent                     | The AI tool or provider used to generate test output, chosen in Settings → AI Model.                                                                  |
| Model                     | The specific AI model and reasoning effort used by the selected agent.                                                                                |
| Generation progress       | The live view that shows queued, running, finalizing, succeeded, failed, or cancelled generation state.                                               |
| Generated output          | The feature, code, screenshots, trace links, or other materials created during generation.                                                            |
| Regenerate                | Run generation again after changing instructions, fixing setup, or wanting a better result.                                                           |

For the full workflow, see [Generate Tests With AI](/ai-generation.md).

## Run Concepts

A run executes tests against a site so you can see whether the behavior works.

| Term               | What it means                                                                                                          |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| Run                | One execution of selected tests.                                                                                       |
| Target site        | The web application URL the run uses.                                                                                  |
| Browser            | The browser used by Playwright during the run.                                                                         |
| Viewport           | The screen size used during the run, such as mobile, tablet, or desktop.                                               |
| Cloud test session | The hardware-isolated sandbox allocated for each run — nothing to install or host.                                     |
| Tunnel device      | A machine inside your network running the `tvtunnel` agent so cloud sessions can reach private apps.                   |
| Configuration      | Saved or selected Playwright settings for a run.                                                                       |
| Automation         | A run triggered on a cron schedule or an external event.                                                               |
| Re-run             | Open the run composer pre-filled from a previous run, so you can review or adjust the selection and start a fresh run. |
| Cancel             | Stop a run that is still active.                                                                                       |

For run setup, see [Choose browser, viewport, and configuration](/run-tests/browser-viewport-configuration.md). For private apps, see [Tunnel devices](/account-settings/tunnel-devices.md).

## Result And Evidence Concepts

Results show whether the run passed and help explain failures.

| Term            | What it means                                                                              |
| --------------- | ------------------------------------------------------------------------------------------ |
| Pass            | The test completed successfully.                                                           |
| Fail            | The test did not meet one or more expected outcomes.                                       |
| Cancelled       | The run was stopped before completion.                                                     |
| Live status     | The current state of a run while it is still moving.                                       |
| Screenshot      | A captured image of the browser at a useful moment, often near a failure.                  |
| Video           | A recording of the browser session during the run.                                         |
| Trace           | A Playwright debugging artifact that can show actions, timing, screenshots, and snapshots. |
| Console output  | Browser messages and errors captured during the run.                                       |
| Network details | Request and response information captured during the run.                                  |
| Failure details | The explanation and evidence TestVibe shows for a failed test or step.                     |

For diagnosis, start with [Inspect failed steps](/results/inspect-failed-steps.md).

## Common Status Words

You may see these words during generation or test runs:

| Status             | What it usually means                                                                             |
| ------------------ | ------------------------------------------------------------------------------------------------- |
| Queued             | TestVibe has accepted the work, but it has not started running yet.                               |
| Preparing          | A cloud test session is being allocated and set up for the run.                                   |
| Running            | The generation or test execution is actively working, with live per-scenario and per-step status. |
| Finalizing         | The main work is done and TestVibe is collecting output, artifacts, or final status.              |
| Passed / Succeeded | The run or generation completed successfully.                                                     |
| Failed             | Something did not complete successfully and needs review.                                         |
| Cancelled          | The work was stopped before it finished.                                                          |
| Error              | The run could not complete because something went wrong outside the tests themselves.             |

If a status looks stuck, see [Run still running or stuck](/troubleshooting/workflow-running-or-stuck.md).

## How The Concepts Fit Together

Most TestVibe work follows this pattern:

1. Open or create a project in your workspace.
2. Organize test intent in the Test Suite.
3. Generate Playwright code with AI.
4. Run the generated test against your site in a cloud test session.
5. Review the result and evidence.
6. Improve the instructions, generated code, or application behavior.

## Where To Go Next

<table data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Get oriented</strong></td><td><ul><li><a href="/pages/82ZgGLTeMmGJcA2oFfc1">What is TestVibe?</a></li><li><a href="/pages/CBsTUnfUWMYV442nEv2V">Who TestVibe is for</a></li><li><a href="/pages/kKNseH0YsIIMPDSgvnNe">Quickstart</a></li></ul></td></tr><tr><td><strong>Create your first test</strong></td><td><ul><li><a href="/pages/KFyP2bFH4rdoYqFMEwha">Understand the Test Suite</a></li><li><a href="/pages/m356yy1w2HcSXx1JbC5U">Gherkin and feature files</a></li><li><a href="/pages/33UtbH87hxyFCMYvvFyo">Write good test instructions</a></li></ul></td></tr><tr><td><strong>Run and review</strong></td><td><ul><li><a href="/pages/EIYfDcimXldXAsAbHFsJ">Generate Playwright code</a></li><li><a href="/pages/N0ItykoTf2IYKz9TZQSp">Cloud test sessions</a></li><li><a href="/pages/bmM92gylZYZkQfqgSjZ4">Run one test</a></li><li><a href="/pages/V2aqM0r3jCbp5jCjqhg0">Read pass/fail status</a></li></ul></td></tr></tbody></table>


---

# 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/readme/key-concepts.md?ask=<question>&goal=<endgoal>
```

`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.