# Quick start

> Install Retest, write a first test, run it and read a failure.

Source: https://rehearsal.dev/retest/quick-start

This guide takes you from an empty project to a test that runs. You need Node.js 24.12 or later, a web app to test, and Chrome, Edge or Chromium.

## Set up a project

1. **Add the package**

   ```sh
   npm install -D @rehearsal-labs/retest typescript @types/node
   ```

   TypeScript is there to check types. Retest loads `.ts` files with the TypeScript support built into Node.js.

2. **Write the starter files**

   ```sh
   npx retest init
   ```

   `init` writes `retest.config.ts`, `tests/example.retest.ts` and `tests/tsconfig.json`. It adds the `test:e2e` and `typecheck:e2e` scripts to `package.json`, and `.retest/` to `.gitignore`. It never overwrites a file.

   At a terminal it asks for your app's address, how to start it and a browser. Give answers as flags, and `--yes` takes the default for the rest:

   ```sh
   npx retest init --app web=http://localhost:3000 --browser chrome --yes
   ```

3. **Check the setup**

   ```sh
   npx retest doctor
   ```

   `doctor` launches each browser once and checks that your app answers. Each problem it finds comes with its fix.

## The config

With the flags above, `init` writes a config like this one. `web` is the app's name, and `chrome()` runs the tests in Google Chrome. When `package.json` has a `dev` or `start` script, `init` also adds a `start` line, so Retest can start your app itself.

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

// Lets every test file see your app names, secrets, test ids and tags.
declare module '@rehearsal-labs/retest' {
  interface Register {
    config: typeof config
  }
}
```

The `declare module` block tells TypeScript your app names, so a typo is a type error. [Types and imports](https://rehearsal.dev/retest/typescript.md) explains it.

## Your first test

This is the test `init` writes. It opens the home page and checks that the page has a main region.

```ts filename="tests/example.retest.ts"
import { expect, test } from '@rehearsal-labs/retest'

test('shows the home page', async ({ page }) => {
  await page.goto('/')
  await expect(page.getByRole('main')).toBeVisible()
})
```

`page.goto('/')` opens the path on the app's `baseUrl`. The check looks at the page again and again until the region is visible, for up to five seconds.

## Run it

```sh
npx retest run
```

Retest runs every `.retest.ts` file under the folder. It prints each test as it ends, then a summary and the exit code. The exit code is 0 when every test passed.

## Read a failure

When a check fails, Retest prints a card. It shows what the check expected, what the page showed and the line where the test stopped.

```text
  ✗ tests/tasks.retest.ts › saves a task  5.6s

    Check failed     toHaveText
    Locator          getByTestId('saved-task')
    Page             http://127.0.0.1:4173/
    - Expected       "Release checklist"
    + Received       "Saving…"
    Compared         whole text, ends trimmed, each run of spaces or line breaks read as one space
    Waited           5s for toHaveText, looked 14 times, limit 5s

    tests/tasks.retest.ts:7:3
      5 │   await page.getByTestId('task-title').fill('Release checklist')
      6 │   await page.getByTestId('save-task').click()
    › 7 │   await expect(page.getByTestId('saved-task')).toHaveText('Release checklist')
      8 │ })

    Screenshot       .retest/runs/<time>/artifacts/…/screenshot-failure-1.png
    Rerun            npx retest run tests/tasks.retest.ts:3
    Inspect          npx retest inspect .retest/runs/<time> --test "tests/tasks.retest.ts > saves a task"
```

The command after **Rerun** runs that one test again. The command after **Inspect** shows every step the test took. [Read a failure](https://rehearsal.dev/retest/essentials/read-a-failure.md) explains each line.

## Next steps

- [Write a test](https://rehearsal.dev/retest/essentials/write-a-test.md) with suites, steps and hooks.
- Find elements the way a person does, with [Locators](https://rehearsal.dev/retest/essentials/locators.md).
- Add apps and browsers in the [Configuration](https://rehearsal.dev/retest/essentials/configuration.md).