> ## Documentation Index
> Fetch the complete documentation index at: https://docs.testorim.com/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript and TypeScript library

> Run Testorim tests from Node code, Playwright Test, Vitest or Jest with the @testorim/cli package.

The [`@testorim/cli`](https://www.npmjs.com/package/@testorim/cli) package (version 0.4.0 and later) is also a JavaScript and TypeScript library: a test suite can run a Testorim test and gate on the verdict. It ships its own types, has no dependencies and needs Node 20 or newer.

```bash theme={null}
npm install --save-dev @testorim/cli
```

Create an API key in Testorim under **Settings → API keys** and put it in `TESTORIM_API_KEY`. See [Authentication](/developers/authentication) for what a key may change.

## From code

```ts theme={null}
import { Testorim } from "@testorim/cli";

const testorim = new Testorim(); // reads TESTORIM_API_KEY

const run = await testorim.runTest(
  "Shop", // a project's name, address or id
  "Add the Blue Top to the cart, open the cart and check that it shows 1 item.",
);
console.log(run.summary());
run.assertPassed(); // throws TestorimRunFailed unless the verdict is passed
```

`runTest` starts the run and waits for the verdict (up to 10 minutes by default). Other calls:

```ts theme={null}
await testorim.projects();                                   // the workspace's projects
await testorim.tests("Shop");                                // a project's saved tests
await testorim.runSaved("Checkout", { project: "Shop" });    // replay a saved test by name or id
await testorim.runTest("Shop", "...", { baseUrl: "https://pr-42.preview.example.com" });
await testorim.runTest("Shop", "Sign in with a wrong password and check that an error is shown.", { expectFailure: true });
const started = await testorim.runTest("Shop", "...", { wait: false }); // start without waiting
await testorim.waitFor(started.id);                          // then wait
await testorim.cancel(started.id);
```

A run has a `verdict` (`passed`, `failed` or `needs_review`; `null` while it runs or when cancelled), the step counts, the written `report`, `failedSteps` (each with the reason and `blame`: `app`, `test`, `unsupported` or `internal`), the run's `url`, and links to the video, Playwright trace and final screenshot, which expire an hour after they were read. `summary()` leaves those links out because it often lands in CI logs.

## In Playwright Test

```ts theme={null}
import { test } from "@playwright/test";
import { Testorim } from "@testorim/cli";

const testorim = new Testorim();

test("checkout works", async () => {
  test.setTimeout(11 * 60_000); // a run takes minutes; the default is 30 seconds
  const run = await testorim.runSaved("Checkout", { project: "Shop" });
  run.assertPassed();
});
```

A failed run fails the test with its summary:

```text theme={null}
TestorimRunFailed: Verdict: FAILED (1 passed, 1 failed, 1 skipped, 41s)
Run: https://app.testorim.com/runs/...
Failed step 2: click "Create account": The page showed Something went wrong [the app did not behave as described]
```

## In Vitest and Jest

Both work the same way; give the test a longer timeout as the third argument: `test("checkout works", async () => { ... }, 11 * 60_000)`. The package is ESM, so run Jest with its ESM support (`NODE_OPTIONS=--experimental-vm-modules npx jest`). A CommonJS project can `require("@testorim/cli")` on Node 20.19 or newer and 22.12 or newer.

## Errors

Every error derives from `TestorimError`, and each is exported:

| Error                 | When                                                                                                                                                     |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AuthenticationError` | 401: the key is missing, wrong or revoked.                                                                                                               |
| `RefusedError`        | 402, 429 or 503: Testorim will not start the run now. `code` and `retryable` say why and whether waiting helps; see [API errors](/api-reference/errors). |
| `NotFoundError`       | No project or saved test matches, or it is in another workspace.                                                                                         |
| `TestorimUnreachable` | The API could not be reached.                                                                                                                            |
| `TestorimRunFailed`   | `assertPassed()` on a run that did not pass.                                                                                                             |
| `TestorimTimeout`     | A wait with `raiseOnTimeout: true` ran out.                                                                                                              |

The client never retries a trigger by itself, because a retried trigger is a second run. If your workspace lives on another host, pass `apiUrl` or set `TESTORIM_API_URL`. The full reference is in the [package README](https://www.npmjs.com/package/@testorim/cli).

## Limits

* The site must be reachable from the internet: Testorim's browsers refuse `localhost` and private addresses.
* Every run counts against your plan, whichever tool started it.
* The same package is the [CLI](/developers/cli) and the [MCP server](/developers/mcp) for coding agents. Working in Python? See [Python and pytest](/developers/python).


## Related topics

- [CLI](/developers/cli.md)
- [Python package and pytest](/developers/python.md)
- [MCP server for coding agents](/developers/mcp.md)
- [Reliability](/troubleshooting/reliability.md)
- [FAQ](/resources/faq.md)