Browser end-to-end tests

import { test } from "bun:test"
import { server } from "@nifrajs/core/server"
import { e2e, expect } from "@nifrajs/e2e"

const html = (body: string) => new Response(body, { headers: { "content-type": "text/html" } })

const app = server().get("/users/:id", (c) =>
  html(`<input aria-label="Nickname" value="ada"><h1>User ${c.params.id}`),
)

test("a user page renders", async () => {
  await using t = await e2e(app)
  await t.open("/users/:id", { params: { id: 42 } }) // a path or param the app lacks fails typecheck
  await expect(t.screen.getByRole("heading")).toHaveText("User 42")
  await t.screen.getByLabel("Nickname").fill("grace")
  await expect(t).toHaveURL("/users/42")
})

import { server } from "@nifrajs/core/server"
import { testSession } from "@nifrajs/testing"
import { e2e, expect } from "@nifrajs/e2e"

const app = server().get("/me", (c) =>
  new Response(`<p>session ${c.cookies.sid ?? "none"}`, { headers: { "content-type": "text/html" } }),
)

// Log in through the API, in process, then hand the cookie jar to the browser.
const { cookies } = testSession<typeof app>(app)
cookies.set("sid", "abc123")

await using t = await e2e(app, { cookies })
await t.open("/me")
await expect(t.screen.getByText("session abc123")).toBeVisible()

import { server } from "@nifrajs/core/server"
import { e2e, expect, Secret, type E2EModel } from "@nifrajs/e2e"

const html = (body: string) => new Response(body, { headers: { "content-type": "text/html" } })

// A sign-in form that lands on a dashboard, so a model has controls to find and a place to end.
const app = server()
  .get("/login", () =>
    html(`<input aria-label="Email"><input aria-label="Password" type="password"><button onclick="location.href='/dashboard'">Sign in`),
  )
  .get("/dashboard", () => html("<h1>Welcome, Ada"))

// The seam to a model. Nothing here names a vendor: you call your provider inside decide().
// doc-check: skip - the provider call is yours; a real adapter would await a model API here.
declare const askMyModel: (request: unknown) => Promise<unknown>
const model: E2EModel = { decide: (request) => askMyModel(request) }

await using t = await e2e(app, { model, agentContext: "Acme calls a plan a seat" })
await t.open("/login")

await t.agent.act("sign in as {email} with {password}", {
  params: { email: "ada@example.test", password: new Secret("password", process.env.PASSWORD ?? "") },
})
await t.agent.assert("the dashboard greets Ada")
await expect(t.screen.getByRole("heading")).toHaveText("Welcome, Ada") // locators and agent steps mix in one test

// What decide() receives and returns, by request kind.
//
//   act      { goal, snapshot, history, secrets, handoff, ... }
//            -> { kind: "tap" | "fill" | "press", target, value?, key? }
//             | { kind: "goto", path } | { kind: "done", summary? } | { kind: "fail", reason }
//   assert   { statement, snapshot }   -> { pass: true | false | "inconclusive", reason }
//   waitFor  { statement, snapshot }   -> { pass, reason }
//   extract  { prompt, snapshot }      -> { value }   (validated with your Standard Schema)
//
// target is one of { role, name? } | { label } | { text } | { testId }, plus exact? and nth?.
// doc-check: skip - protocol sketch, not code.

import { server } from "@nifrajs/core/server"
import { t as s } from "@nifrajs/schema"
import { e2e } from "@nifrajs/e2e"

const app = server().get("/plan", () => new Response("<p>Pro, 5 seats", {
  headers: { "content-type": "text/html" },
}))

const model = {
  decide: () => ({ value: { plan: "Pro", seats: 5 } }), // a real model reads the outline in the request
}

await using t = await e2e(app, { model })
await t.open("/plan")
const plan = await t.agent.extract("the current plan and seat count", {
  schema: s.object({ plan: s.string(), seats: s.number() }),
})
plan.seats // number

import { server } from "@nifrajs/core/server"
import { e2e, expect, formatReport, unique, type E2EModel } from "@nifrajs/e2e"

const app = server().get("/signup", () => new Response("<h1>Sign up", {
  headers: { "content-type": "text/html" },
}))
const model: E2EModel = { decide: () => ({ kind: "done" }) }

await using t = await e2e(app, {
  model,
  cache: { testId: "a visitor signs up", mode: "read-write" },
})
await t.open("/signup")

// unique() keeps a run-varying value from missing the cache; it is typed again on replay.
await t.agent.act("sign up as {email}", { params: { email: unique(`ada-${Date.now()}@example.test`) } })

// The recording is written only when a LATER check passes.
await expect(t.screen.getByRole("heading")).toBeVisible()
console.log(formatReport(t.agent.report())) // Cache: 1 replayed - 0 handed off - 0 missed (0 model calls)

import { server } from "@nifrajs/core/server"
import { e2e, expect } from "@nifrajs/e2e"

const html = (body: string) => new Response(body, { headers: { "content-type": "text/html" } })

const app = server()
  .get("/", () => html('<a href="/dashboard">Dashboard'))
  .get("/dashboard", () => html("<h1>Dashboard"))

// CI replays committed recordings and never writes or deletes them. With no model, a recording that
// no longer matches fails with MODEL_MISSING; mode: "strict" fails with REPLAY_STALE (or
// REPLAY_MISSING when nothing was recorded) instead of ever calling a model.
await using t = await e2e(app, { cache: { testId: "home to dashboard", mode: "strict" } })
await t.open("/")
await t.agent.act("open the dashboard") // reads the committed recording; strict mode checks it here
await expect(t.screen.getByRole("heading")).toHaveText("Dashboard")

import { server } from "@nifrajs/core/server"
import { e2e } from "@nifrajs/e2e"
import { fakeEngine } from "@nifrajs/e2e/fake"

const app = server().get("/", () => new Response("ok"))

// An in-memory engine with the same locator rules, for testing code built on this package.
const { factory } = fakeEngine({ pages: { "/": [{ role: "heading", name: "Home", text: "Home" }] } })
await using t = await e2e(app, { engine: factory, cache: false })
await t.open("/")
await t.screen.getByRole("heading").count()