Recipes
Recipes for brewing great tests. 🍺
Recipes are short, real-world patterns that combine CraftDriver features into common testing workflows. Use this page as the index; each recipe has its own page so the list can grow without turning into a wall of code. New here? Start with Find Elements On The Page — every other recipe builds on knowing how to point at the thing you want.
Every snippet is verified in CI against a live example page you can open yourself, under dtopuzov.github.io/craftdriver/examples. To stay readable, a snippet shows only the code it is teaching and assumes a launched browser — unless it shows a Browser.launch(...) call itself. See the Vitest Hooks recipe for the surrounding setup.
The Electron recipes are different: they show the project shape for driving a packaged desktop app, so they use paths you adapt to your app repo rather than the hosted browser examples. The BrowserStack recipe is also different: it needs real provider credentials. Its live test is credential-gated, runs only for trusted repository events, and is skipped for forks.
For exact signatures, use the linked feature docs and the API reference.
Start Here
| Scenario | Use when | Recipe |
|---|---|---|
| Find elements | You're new and need to point CraftDriver at the element you want. | Find Elements On The Page |
Test Structure
| Scenario | Use when | Recipe |
|---|---|---|
| Vitest browser lifecycle | You want one browser per test file and a fresh page per test. | Use CraftDriver With Vitest Hooks |
| Login once, reuse session | Login UI is slow or noisy and most tests start signed in. | Log In Once And Reuse The Session |
| Multi-user flows | You need Alice and Bob signed in at the same time without leaking cookies. | Test Multi-User Workflows |
| Page objects | Selectors and steps are copy-pasted across tests and break together. | Organize Flows With Page Objects |
App Behavior
| Scenario | Use when | Recipe |
|---|---|---|
| Mock APIs and assert traffic | A UI flow depends on backend responses or request payloads. | Mock APIs And Assert Network Traffic |
| Time-sensitive UI | Debounces, trial banners, idle logout, or scheduled jobs make tests slow. | Test Time-Sensitive UI With The Virtual Clock |
| Mobile-specific behavior | Mobile layout depends on viewport, device headers, API config, or logs. | Test A Mobile Flow With API Mocks And Logs |
| File upload and download | A flow uploads a file, exports a report, or verifies downloaded content. | Test File Uploads And Downloads |
AI Agents
Give your coding agent a real browser so it writes tests against what your app actually renders, instead of guessing selectors from source.
| Scenario | Use when | Recipe |
|---|---|---|
| AI-assisted testing | Claude Code, Codex, or Copilot should explore the live app, add a test, or audit accessibility. | Ask Your Agent To Write A Browser Test |
Quality Gates And Debugging
| Scenario | Use when | Recipe |
|---|---|---|
| Accessibility regression gate | CI should fail on serious page or component accessibility issues. | Run Accessibility Gates |
| Console and JavaScript errors | Tests should fail if the browser reports unexpected client-side errors. | Fail On Console And JavaScript Errors |
| Debug failing tests | You need the actions, screenshots, logs, and network activity behind a failure. | Use Traces To Debug Failing Tests |
External Providers
Running against a remote Grid or cloud provider instead of a local browser. This recipe needs provider credentials. Its live test is credential-gated, runs on trusted pushes and pull requests, and is skipped for forks — see tests/recipes/README.md.
| Scenario | Use when | Recipe |
|---|---|---|
| Run on BrowserStack | You want to run against real browsers/devices in the cloud. | Run On BrowserStack |
Electron
Driving a packaged Electron desktop app. These use paths you adapt to your app repo rather than the hosted browser examples, and the mocking/deep-link recipes need main-process access (electron: { mainProcess: true }). See Testing Electron Apps for setup, drivers, and the security boundary.
| Scenario | Use when | Recipe |
|---|---|---|
| Electron app from another repo | Your packaged Electron app is built in one repo and tested from another. | Test An Electron App From Another Repo |
| Electron native dialog | A renderer flow opens an operating-system file, save, or message dialog. | Mock A Native Electron File Dialog |
| Electron API mocking | A flow calls shell.openExternal, clipboard.writeText, or similar. | Mock Electron APIs |
| Electron deep link | Your app registers a myapp:// scheme and must handle links from the OS. | Test An Electron Deep Link |