Activity
Contributors
README
Retest is a test runner and automation engine written from scratch, with its own drivers for Chromium, Firefox, WebKit, iOS simulator apps, macOS apps and Electron. One test can move between them, every action follows fixed rules, and AI only judges evidence when a test asks it to.
There is no Playwright, Puppeteer or Selenium underneath. Retest is early, and this page says plainly what runs today.
Quick start
You need Node.js 24.12 or later, on macOS or Linux.
TypeScript is only for type checks. Retest runs .ts test files without it.
retest init writes retest.config.ts, an example test and a tsconfig.json for your tests. It asks for your app's address and browser, or takes them as flags: npx retest init --app web=http://localhost:3000 --browser chrome. It never overwrites a file.
Write your first test in tests/task.retest.ts:
Run every .retest.ts file under the folder:
If a browser, a server or a secret is not ready, doctor says what is wrong and how to fix it:
Browsers
chrome() runs the Google Chrome installed on your machine. chromium() runs the Chromium build you point it to.
Retest downloads nothing unless you ask. retest install fetches a pinned build and checks its SHA-256 before it unpacks anything:
On macOS on Apple silicon, Retest pins Chrome for Testing, Firefox 133, Playwright's WebKit build 2359 and Electron 44.5.1. On Linux x64 it pins Chrome for Testing only. A Firefox target finds the installed build by itself. Give a Chromium, WebKit or Electron target the path that retest install prints.
What runs today
| Browsers | Chrome and Chromium. Firefox 133 and WebKit build 2359 on macOS on Apple silicon |
| iOS simulator apps | Find, tap, fill and check elements through WebDriverAgent, built on your Mac from a pinned commit |
| macOS apps | Find, click, fill and check elements through the macOS runner of appium-mac2-driver |
| Electron apps | The app's first window, driven like a Chrome page. Checked with Electron 44.5.1 on macOS |
| One test across platforms | An iOS simulator app, a macOS app and web apps in the same test |
| AI checks | test.evaluate asks a judge you choose whether a screenshot, text or recorded frames meet a requirement |
| Layout checks | Overlapping elements, cut-off text, an element past the viewport's right edge and sideways scroll, each measured in pixels. Checked on Chrome on macOS |
| Screenshot baselines | A page or an element compared to a saved image, pixel by pixel, with the difference in the report. Checked on Chrome on macOS |
| Test inboxes | A test reads a one-time code and a sign-in link from a mailbox your config reads, types and opens them, and never holds either. Checked on Chrome. The guide says how |
| Files | Upload by path or content, intercept the file picker, save downloads as artifacts. Checked on Chrome on macOS |
| Dialogs and popups | Accept or dismiss alert, confirm, prompt and beforeunload; drive a page the app opens. Checked on Chrome on macOS |
| Mocked responses and drag | Answer a request with your own response or refuse it; drag an element onto another. Checked on Chrome on macOS |
| Playwright test files | retest run --playwright runs .spec.ts files unchanged, for the methods the guide lists |
| Linux | Chrome and Chromium only, checked inside Docker |
Not yet: Android apps, Windows, Safari, and real phones or tablets.
One test across platforms
This test creates a task on an iPhone simulator, marks it done in Chrome, and sees it done in a macOS app. It is shortened from reference-flow.retest.ts, which runs against the fixture apps in that folder.
The password reaches each app through secret(), never through the test's source. The test has no sleeps. Each check keeps looking until the change from the other app arrives.
See exactly what went wrong
A failure is one card: the check, the element, what was expected, what the page showed, how long Retest looked, the line in your test, a screenshot, and the commands to rerun and inspect it. This is examples/task.retest.ts, the test above, run against an app that drops the last letter of every title. Paths are shortened.
Give your coding agent the same facts
When a coding agent runs Retest, Retest notices. The output gets short, and ends with the next command to run.
Every run also writes versioned events, one JSON object per line, with a published JSON Schema. Here is one, shortened:
retest inspect reads a run folder without running anything again. A run that was cut off can never read as a pass.
What makes it different
- It says what happened, not what it hopes happened. A test with no assertions fails. A forgotten
awaitfails and names its line. If the browser dies after a click was sent, the result is "outcome unknown", never a guess. - Real input. A click goes through the mouse at the element's centre, after checking it is visible, still, enabled and not covered. A covered button is refused. Nothing is force-clicked.
- Checks look again. Actions never repeat. An assertion keeps reading the page until its deadline. A click is sent once.
- Made for agents from the start. Finite commands, stable test ids, exit codes that mean something (
0,1,2,130,143), and output an agent can act on. - Nothing hidden. No account and no telemetry. Nothing downloads unless you run
retest install. Screenshots stay on your machine unless an AI check sends one to the judge you chose. - Zero runtime dependencies. The AI SDK packages are optional peers, loaded only by a judge that uses them.
Documentation
- The guide: the config, the test API, the command line and their limits, in detail.
- Architecture: the design Retest was built from.
- Playwright compatibility: the same test files run by Playwright and by Retest, case by case.
- Conformance: fixed cases on Chrome, Firefox and WebKit, and where each engine differs.
- rehearsal.dev/retest: the documentation site.
Contributing
Read CONTRIBUTING.md before you open a pull request.
From the team behind Rehearsal
Retest is built by Rehearsal, where an agent writes your tests, keeps them working and reports on every pull request. You never need Rehearsal to use Retest.