Scenarios: a site proves what it does

Ask AI

Use this guide to write a site’s scenarios and to play them before a merge. A scenario is a short story about the site’s visitors: they open pages, send forms and follow links, and the scenario says what each page shows after each step.

Where they go

Each file of scenarios is tests/<name>.test.ts at the top of the site, one file per part of the site. A file holds scenario(name, fn) calls, each one story that starts from empty tables of its own. The site’s real rows are never read or written.

scenario("a signed entry reaches another visitor's open guest book", () => {
  const annBook = anonymous().open("/guestbook")
  const bobBook = anonymous().open("/guestbook")
  annBook.submit("sign", { name: "Ann", message: "The rye was still warm." })
  bobBook.sees("The rye was still warm.")
})

What a scenario can do

Call	Does
`anonymous()`	A visitor who is not signed in, with no page open yet.
`who.open(path)`	A new tab of that visitor at that path, redirects followed. It stays open and live until it is closed.
`page.submit(formId, values)`	Sends a form the tab shows, with those values. The tab then shows the form’s answer or where it led.
`page.follow(text)`	Follows the one link whose text contains that text.
`page.sees(text)`, `page.seesNot(text)`	What a person could read on the tab now.
`page.is(404)`, `page.redirectsTo(path)`	How the request that loaded the tab was answered.
`page.close()`	Closes the tab.
`page.path`	Where the tab is.
`rows(table)`, `add(table, {...})`	As the owner: every row of a table, and a row to start from.

signIn, force, types and after are not available yet, and a file that uses one is refused before anything plays. Write each check as a call above: expect(...) is refused with the line to write instead.

Play them

Call run_tests with the branch. It answers each scenario by name. One that fails names its line, what did not hold, and what the page showed, so fix the page and not the scenario unless the scenario is what is wrong. A file with an error in it plays none of its scenarios and says why under problems.

merge_branch refuses to put a branch live while one of its scenarios fails, or while a test file cannot be read. The site’s owner sees each scenario and whether it passes on the branch’s page in the dashboard, and may still merge it from there.