# Test

**Help URL:** `/forms/test`

## Purpose

Define a test (name + steps + optional dependency) and generate/update the corresponding Playwright test file under `Tests/` in your project repository.

## Quick Start

1. Enter a **Test name**.
2. (Optional) Choose a **Group** to organize the file under `Tests/<Group>/`.
3. (Optional) Choose a **Prerequisite** test.
4. Set **Site URL** (defaults to the repository homepage).
5. Add at least one **Step**.
6. Click **Create/Update** to dispatch generation.

## How Generation Works

* TestVibe dispatches the GitHub Actions workflow `generate-test-v1.yml` in your project repository.
* It passes the steps and metadata (site URL, target file path, optional dependency path) as workflow inputs.
* TestVibe tracks the workflow run and can open a live "generation run" view while it's in progress.

## Files, Naming, and Groups

* Test files live under `Tests/`.
* The **Test name** is sanitized into a file name and forced to end with `.test.js`.
* If a **Group** is selected, the target path becomes `Tests/<Group>/<file>.test.js`.
* When editing an existing test, changing the name/group can rename the underlying file in the repository.

## Prerequisites (Dependencies)

Dependencies let you mark another test as a prerequisite for this test.

* Selecting a prerequisite stores a path relative to `Tests/` (for example: `Login/login.test.js`).
* TestVibe resolves dependency selection from either:
  * a display label like `Group / TestName`, or
  * a Tests-relative file path.
* If the current test is a prerequisite for other tests, TestVibe shows a warning banner because regenerating it may break dependents.

## Writing Good Steps

* Keep each step focused (one user action or one assertion per step).
* Include critical assertions explicitly (for example: "Verify ...") so generation doesn't guess.
* Prefer concrete UI references (for example: "Click Save button in the toolbar") over vague descriptions.

## Secrets and Tokens (Required for Generation)

Generating tests requires repository secrets (TestVibe prompts when missing):

* `GH_PAT`: Set automatically each time you generate by minting a short-lived Git token (GitHub App installation token when available, otherwise the signed-in OAuth token) and storing it in the repo secret.
* `OPENAI_API_KEY`: Prompted once (if missing) and stored as a repo secret.

Test generation also uses a per-run TestVibe token (issued and later revoked best-effort) for workflow-to-TestVibe API calls.

## Related Tools

* **View/edit code:** Use **Code** (edit mode) to open the file in the [Editor](/reference/forms/editor.md).
* **Record steps:** Use **Recorder** to download a recorder bundle and upload recorded steps back into TestVibe ([Recorder (Playwright)](/reference/forms/recorder-help.md)).

## Troubleshooting

* "Duplicate Test File": change the test name and/or group so the target path is unique under `Tests/`.
* "Failed to obtain a GitHub token...": ensure the TestVibe GitHub App is installed for the account and you have access to the repository.
* Prompted for `OPENAI_API_KEY`: enter a valid key (it is stored as a repository secret for future runs).

## Notes

* TestVibe shows a short guided tour for this form once per browser (cookie `testvibe.tour.test`).


---

# 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/reference/forms/test.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.