DocsTesting
Testing
Tests of your whole app, written as Playwright writes them and run by Sluurp itself, in the admin or headless, with coverage.
Put tests in your app’s tests/ folder and Sluurp runs them. Run them in the admin, where you watch each one drive your app, or headless with sluurp test for CI. There’s no Node and no Playwright to install; Sluurp uses the Chrome or Edge already on your machine. To write a test:
import { expect, test } from "sluurp/test";
test("a note is added", async ({ page }) => {
await page.goto("/notes");
await page.getByLabel("Title").fill("Milk");
await page.getByRole("button", { name: "Add" }).click();
await expect(page.getByText("Milk")).toBeVisible();
});
test("only a signed-in person may list notes", async ({ request, admin }) => {
expect((await request.get("/api/collections/notes/records")).status).toBe(403);
expect((await admin.get("/api/collections/notes/records")).ok).toBe(true);
});Features include:
- Playwright’s API: locators, actions that wait, and checks that retry
- A run in the admin where you watch each test, and run again on save
- Headless runs for CI, with coverage as
lcov.info - Plugins tested the same way, from their own folder
- Data made from TypeScript types with
mock<T>()
Write a test
Each test gets three things:
page: your app in a fresh frame, driven as a person would. It hasgoto,reloadandlocator, plusgetByRole,getByText,getByLabel,getByPlaceholderandgetByTestId. What those return hasclick,fill,press,check,hover,textContentand more.request: your API, as someone who isn’t signed in.admin: your API as a superuser, for setting data up.
Every action waits until its element is on the page and visible. Inside an island, it also waits until the island has hydrated.
expect on a locator or the page retries until the check holds, for up to 5 seconds, as in Playwright. The checks are toBeVisible, toBeHidden, toHaveText, toContainText, toHaveCount, toHaveValue, toHaveAttribute, toBeChecked, toBeEnabled, toBeDisabled, toHaveURL and toHaveTitle. On any other value, expect checks once. expect.poll(() => value) asks again until the check holds.
Group tests with test.describe, set things up with test.beforeEach, test.afterEach, test.beforeAll and test.afterAll, and narrow a run with test.only and test.skip.
Run tests in the admin
Tests in the admin’s sidebar lists your test files and runs them. Each test’s frame is shown while it runs, and you can choose a result to see its steps and what failed. Turn on Auto-run and a test file you save runs again at once, without the page reloading. A change to the app itself runs every test again.
Run tests headless
sluurp test --public appYour app is served on a fresh database, and its tests run in a headless Chrome, Edge or Chromium. Results are printed as they come, and a failed test makes the command exit with code 1, for CI. Use --grep to run only the tests whose name contains a word, and --browser-path or SLUURP_BROWSER to name the browser. With --no-browser, no browser is started: the command prints the run’s address, and the tests start when you open it in a browser on the same machine. That is useful when you want to watch them, or when no Chrome is installed.
A plugin is tested the same way, from its folder in a plugins repository: sluurp test --public plugins/invoices. It is installed into an app made for the run, with the plugins it requires: those beside it in the repository are copied, and the rest are installed from the registry.
Coverage
sluurp test --public app --coverageThis reports which lines of your app’s code the tests ran in the browser, file by file. It also writes coverage/lcov.info, which coverage services and editors can read. Pages drawn on the server run there, so they aren’t measured in the browser.
Data from types
mock<T>() from sluurp/schema makes values of a type, for a story, a test or a page that has no data yet. schemaOf<T>() gives the type’s JSON Schema.
import { mock, schemaOf } from "sluurp/schema";
interface Customer { name: string; email: string; age: number; plan: "free" | "pro" }
const customers = mock<Customer>(20); // twenty customers
const one = mock<Customer>(); // one
const shape = schemaOf<Customer>(); // its JSON SchemaThe values are plausible for their names and types: a name gets a person’s name, an email an address, a price an amount, and a union one of its members. They’re the same on every run, so a story or a test sees the same data each time. The type is read where the call is written, so it has to be declared in the same file.
schemaOf<T>() is a Standard Schema too. Anything that takes zod’s schemas takes it as well: a route’s or a hook’s input, React Hook Form’s resolver, or ctx.ai. shape["~standard"].validate(value) returns the value if it fits the type, or the problems with it.
Components on their own
A component’s stories are tests too: each story’s play runs in the Storyboard’s Test tab. See Storyboard.