# Key concepts

This page explains the main TestVibe terms you will see while setting up a workspace, 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>Workspace</strong></td><td>The GitHub-connected place where your team works on one selected repository.</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 stored in your repository.</td><td><a href="/pages/W3i7XJVOFjRvYAOMTe50">/pages/W3i7XJVOFjRvYAOMTe50</a></td></tr><tr><td><strong>Runner</strong></td><td>The GitHub Actions machine 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 connect TestVibe to GitHub.

| Term                    | What it means                                                                                    |
| ----------------------- | ------------------------------------------------------------------------------------------------ |
| Account                 | Your TestVibe user account, connected to your GitHub identity.                                   |
| GitHub App installation | The GitHub App access that allows TestVibe to work with selected repositories.                   |
| Team                    | A group of users or repository access context, often tied to a GitHub organization.              |
| Repository              | The GitHub repository where TestVibe stores generated test files and workflow configuration.     |
| Project                 | The TestVibe view of a repository and its testing setup.                                         |
| Site URL                | The web application address your tests run against.                                              |
| Repository settings     | The project-level settings that affect generation, runs, agents, and framework guidance.         |
| Runner settings         | The repository setting that tells TestVibe which GitHub Actions runner labels to use by default. |
| API key or secret       | A value needed for generation or workflows, stored securely rather than typed into every run.    |

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 repository.                                     |
| 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.               |
| Generated Playwright code | The JavaScript test file produced from your test intent.                                                |
| Agent                     | The AI tool or provider used to generate test output.                                                   |
| Model                     | The specific AI model used by the selected agent, when configurable.                                    |
| 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.                            |
| Runner        | The GitHub Actions machine that prepares the environment and executes the workflow.                 |
| Runner labels | The labels GitHub uses to choose a matching runner, such as `ubuntu-latest` or a self-hosted label. |
| Configuration | Saved or selected Playwright settings for a run.                                                    |
| Scheduled run | A run configured to happen later or repeatedly.                                                     |
| Re-run        | Start a new run using a previous run or selection as the starting point.                            |
| Cancel        | Stop a run that is still active.                                                                    |

For run setup, see [Choose browser, viewport, and configuration](/run-tests/browser-viewport-configuration.md). For execution environment setup, see [Runners](/runners.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 or GitHub has accepted the work, but it has not started running yet.        |
| Setting up | The runner is preparing dependencies, browser tools, configuration, or environment.  |
| Running    | The generation or test execution is actively working.                                |
| Finalizing | The main work is done and TestVibe is collecting output, artifacts, or final status. |
| Succeeded  | The generation or run completed successfully.                                        |
| Failed     | Something did not complete successfully and needs review.                            |
| Cancelled  | The work was stopped before it finished.                                             |
| Missing    | TestVibe expected a file, secret, repository, or artifact but could not find it.     |

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

## How The Concepts Fit Together

Most TestVibe work follows this pattern:

1. Select a repository 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.
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">Runners</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: 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/readme/key-concepts.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.