# Quick start > Install Retest, run your first test and inspect a failure with an agent or by hand. Source: https://rehearsal.dev/retest/docs/quick-start This guide takes you from installing Retest to running a test against your web app. You can give the setup to a coding agent or follow the steps yourself. The first test needs no AI provider. > [!NOTE] > **Requirements** > > Use Node.js 24.12 or later on macOS, or on Linux with Chrome or Chromium, where Retest is checked inside Docker. You also need a web app to test and Google Chrome installed; for another browser, follow [Browsers](https://rehearsal.dev/retest/docs/platforms/browsers.md). Run every `retest` command in the project where you installed it: elsewhere, `npx retest` would fetch an unrelated npm package with the same name. ## Set up with your coding agent Open Claude Code, Codex or Cursor in your app's directory and paste this prompt. It asks the agent to inspect your project before choosing the commands and flow: **Prompt for your coding agent** ```text Set up Retest end-to-end tests in this project. Read https://rehearsal.dev/retest/docs/quick-start.md first, then follow the linked docs when needed. 1. Read the project instructions, package manager, start scripts and existing tests. Check for Node.js 24.12 or later and an installed supported browser. 2. Install @rehearsal-labs/retest, typescript and @types/node as development dependencies with this project's package manager. 3. Run retest init with explicit --app, --browser and --start flags for this app, or --yes for defaults you have checked. Review the generated config and keep existing files. 4. Run retest doctor and resolve setup problems before running tests. Reuse an app server that already answers. 5. Replace the generated example with one test for an important user flow. Read the app's actual labels and test ids. Await every action and asynchronous check, and verify the outcome with expect. 6. Run the test. On failure, read the report and follow its next inspection command. Fix the cause and rerun until the test passes, without weakening its checks to hide a bug. 7. Add the test and type-check commands to the project instructions. Report what you tested and any setup you could not verify. Do not add an AI judge for the first test. If the flow needs credentials, declare them as config secrets and use secret handles in the test. ``` Retest prints shorter output when it detects a coding agent, including the command to inspect the run. [Coding agents](https://rehearsal.dev/retest/docs/coding-agents.md) explains that workflow and gives project instructions you can keep for later tests. ## Set up by hand 1. **Install the package** In your app's directory, install Retest and the packages used to check your test types: **npm** ```sh npm install -D @rehearsal-labs/retest typescript @types/node ``` **pnpm** ```sh pnpm add -D @rehearsal-labs/retest typescript @types/node ``` **yarn** ```sh yarn add -D @rehearsal-labs/retest typescript @types/node ``` **bun** ```sh bun add -d @rehearsal-labs/retest typescript @types/node ``` Retest runs your `.ts` tests with the TypeScript support built into Node, so the TypeScript package is only there to check types. Tests and the config use ES module imports. If Node prints a warning about the module format, [TypeScript](https://rehearsal.dev/retest/docs/essentials/typescript.md) explains the `"type"` field in `package.json` and when it is safe to change. 2. **Create the config and starter test** Run `init` and answer its questions about your app's address, start command and browser: **npm** ```sh npx retest init ``` **pnpm** ```sh pnpm exec retest init ``` **yarn** ```sh yarn retest init ``` **bun** ```sh bunx retest init ``` `init` writes `retest.config.ts`, `tests/example.retest.ts` and `tests/tsconfig.json`. It also adds test and type-check scripts to `package.json`, and `.retest/` to `.gitignore`, while keeping existing files and scripts. For a command without questions, give explicit flags. Replace the example address with your app's address: ```sh npx retest init --app web=http://localhost:3000 --browser chrome --yes ``` The config below uses Chrome at that address. Your generated config may also have a `start` command, which lets Retest start the app when no server answers. ```ts filename="retest.config.ts" import { chrome, defineConfig } from '@rehearsal-labs/retest' const config = defineConfig({ apps: { web: chrome({ baseUrl: 'http://localhost:3000' }), }, }) export default config declare module '@rehearsal-labs/retest' { interface Register { config: typeof config } } ``` `web` names the app, and `baseUrl` is the address relative paths open against. Keep the registration block at the bottom so TypeScript can check app names and other config values used by tests. 3. **Check that the browser and app are ready** Start your app if the config has no `start` command, then run the setup check: **npm** ```sh npx retest doctor ``` **pnpm** ```sh pnpm exec retest doctor ``` **yarn** ```sh yarn retest doctor ``` **bun** ```sh bunx retest doctor ``` `doctor` launches and closes the browser, checks that the app answers and checks configured secret variables. It runs no tests. If it finds a problem, follow the reported fix before continuing. 4. **Write a test for your app** The generated test opens `/` and checks for a main region. Rename `tests/example.retest.ts` to `tests/task.retest.ts` and replace its contents with this example. It expects the task app's test ids, so change the locators and expected title to match your app. ```ts filename="tests/task.retest.ts" import { expect, test } from '@rehearsal-labs/retest' test('saves a task', async ({ page }) => { await page.goto('/') await page.getByTestId('task-title').fill('Release checklist') await page.getByTestId('save-task').click() await expect(page.getByTestId('saved-task')).toHaveText('Release checklist') }) ``` The test fills the title field, clicks Save once and waits for the saved title. Await each action and check so the steps run in order. The final check waits up to five seconds by default, so you need no fixed sleep while the app saves. 5. **Run the test** **npm** ```sh npx retest run ``` **pnpm** ```sh pnpm exec retest run ``` **yarn** ```sh yarn retest run ``` **bun** ```sh bunx retest run ``` Retest discovers `.retest.ts` files below the current folder and runs them using your config, then prints a summary and the run folder. A successful run exits with code 0. While editing, run only this file by adding `tests/task.retest.ts` after `run`. ## Read a failure A failed check shows what Retest expected and what the page showed instead. For example, if the app drops the last letter of the title, these lines explain the mismatch: ```text Check failed toHaveText Locator getByTestId('saved-task') - Expected "Release checklist" + Received "Release checklis" ``` The full report also names the source line, the wait and any captured screenshot, then prints commands to rerun and inspect the test. Copy its inspection command to read the saved steps. Inspection opens no browser and changes nothing in the app. ```sh npx retest inspect .retest/runs/