@orieljs/framework 0.1.0-alpha.1 → 0.1.0-alpha.11

package/docs/installation.md

@@ -0,0 +1,219 @@
+# Installation
+
+Oriel is a full-stack TypeScript framework for Node and Bun, in the spirit of Laravel. Create an app with your
+package manager and one of seven starter kits.
+
+## Meet Oriel
+
+Oriel gives a TypeScript app what Laravel gives a PHP one: routing, controllers and middleware, models and
+migrations, validation, authentication, queues, mail and the scheduler, under Laravel's names. Your pages are Inertia
+pages in React, Vue, Svelte, Solid or Angular, or Live components rendered on the server, and the same app can serve a
+JSON API.
+
+## Creating an Oriel application
+
+### Requirements
+
+You need **Node 22** or later, or **Bun 1.2** or later. Nothing is installed globally: the installer runs through
+your package manager, and each app has its own `oriel` command. A new app keeps its data in SQLite, so you don't need
+a database server to start.
+
+### Creating an application
+
+Create an app with your package manager's `create` command:
+
+```sh
+npm create @orieljs@latest blog
+```
+
+The same installer runs with pnpm, Bun and Yarn:
+
+```sh
+pnpm create @orieljs blog
+bun create @orieljs blog
+yarn create @orieljs blog
+```
+
+`npm create oriel-app` is the same installer under another name: both run `create-oriel-app` at the same version.
+
+The installer asks for the app's name, unless you gave one, then for a stack (Inertia, Live or an API) and, for Inertia,
+its framework, and last whether to install the dependencies and start a git repository. The name is the last part of the
+folder you create the app in, and it must be a valid npm package name: lower case, with no spaces. When the folder isn't
+empty, the installer asks before it removes the files in it.
+
+### Choosing a starter kit
+
+The kits with pages come with registration, login, email verification, password reset, a dashboard, and profile,
+password and appearance settings. The API kit has registration, login, logout and password reset as JSON endpoints,
+with personal access tokens and no pages. Pick one in the prompt, or name it with an option:
+
+| Option | The kit |
+| --- | --- |
+| `--inertia=react` | Inertia pages in React (a bare `--inertia` means React) |
+| `--inertia=vue`, `--inertia=svelte`, `--inertia=solid`, `--inertia=angular` | Inertia pages in Vue, Svelte, Solid or Angular |
+| `--live` | Live: server-driven components written in TSX |
+| `--api` | A JSON API with personal access tokens, and no pages |
+
+[Starter kits](starter-kits.md) describes what each kit contains.
+
+> [!NOTE]
+> With npm, the options go after `--`, so npm passes them on to the installer:
+> `npm create @orieljs@latest blog -- --inertia=vue`. pnpm, Bun and Yarn take them directly.
+
+### Installer options
+
+| Option | What it does |
+| --- | --- |
+| `--pm <npm\|pnpm\|yarn\|bun>` | The package manager to use (by default, the one running the installer) |
+| `--install`, `--no-install` | Install the dependencies, set the app key, create the database and build the assets (default: yes) |
+| `--git`, `--no-git` | Start a git repository with a first commit (default: yes) |
+| `-f`, `--force` | Empty a folder that isn't empty, without asking (a `.git` folder stays) |
+| `-y`, `--yes` | Ask nothing, and take the defaults for everything not given: `oriel-app`, React, install, git |
+| `-h`, `--help` | List the options |
+| `-v`, `--version` | Print the installer's version |
+
+The installer asks its questions only in a terminal: when its input and output are a terminal, the `CI` variable isn't
+set and you didn't pass `--yes`. In a script or on CI, pass the kit as an option or `--yes`; without either, the
+installer stops with "No stack chosen: pass --inertia[=<framework>], --live or --api (or --yes for React).". A folder
+that isn't empty needs `--force` there.
+
+### What the installer does
+
+It copies the kit into the new folder and writes the app's `package.json` for your package manager. It writes `.env`
+from `.env.example`, with `APP_NAME` set to the app's name, and a CI workflow, `.github/workflows/ci.yml`, that
+installs the app, migrates a fresh database, type-checks and tests the app, builds its assets, and checks that it
+serves. The workflow runs on Node 22, Node 24 and Bun, or on Bun alone for an app made with Bun.
+
+Unless you pass `--no-install`, it then runs the first commands for you:
+
+```sh
+npm install
+node oriel key:generate
+node oriel migrate --force
+npm run build
+```
+
+`key:generate` writes your app's secret key, `APP_KEY`, into `.env`, and `migrate` creates the SQLite database,
+`database/database.sqlite`, with the tables a new app needs: users, password reset tokens, sessions, cache, cache locks,
+jobs, job batches, failed jobs, personal access tokens and notifications. The API kit has no assets, so it has no
+`build` step.
+
+Last, unless you pass `--no-git`, it runs `git init` and makes a first commit, "Initial commit". It skips this when
+git isn't installed or the folder is inside a git repository already. When the commit fails, for example because
+git has no `user.name` and `user.email` yet, the repository stays, with your files added but not committed.
+
+### Package managers
+
+The installer works with npm, pnpm, Yarn (Yarn 1, and Yarn 2 or later such as Yarn 4) and Bun. The app it writes
+follows the one you chose:
+
+- **pnpm:** `package.json` names pnpm and its version in `packageManager`, and `pnpm-workspace.yaml` lists the
+  dependencies allowed to run install scripts (before pnpm 10.26, a `pnpm` field in `package.json` does).
+- **Yarn 2 or later:** `package.json` names Yarn and its version in `packageManager`, and `.yarnrc.yml` sets
+  `nodeLinker: node-modules`, since the app's tools don't run under Plug'n'Play. Yarn 1 needs neither.
+- **Bun:** the app runs `bun oriel` wherever another app runs `node oriel`: in its scripts, in the commands the
+  installer runs and prints, and in its CI workflow, which runs on Bun only.
+
+The commands in the kit's `README.md` are rewritten for your package manager too.
+
+## Running your application
+
+When the installer is done, it prints the commands to run while you work:
+
+```sh
+cd blog
+npm run dev
+node oriel serve --watch
+```
+
+Run the last two in two terminals. In one, `npm run dev` starts Vite, which serves your pages' scripts and styles and
+updates them in the browser as you edit them. In the other, `node oriel serve --watch` starts your app's server.
+
+Your app is at [http://localhost:8000](http://localhost:8000). `--watch` restarts the server when a file it runs
+changes: a TypeScript, JavaScript or JSON file in `app`, `bootstrap`, `config`, `lang`, `resources/lang`,
+`resources/views` or `routes`, `.env` or another `.env.*` file (not `.env.example`), `package.json` or
+`tsconfig.json`. Your pages' own scripts and styles, in `resources/js` and `resources/css`, are Vite's, and don't
+restart it.
+
+> [!NOTE]
+> Vite reloads the page when a view, a route file or a Live component changes, often before the server has
+> restarted, and it doesn't reload the page again once the new server is up. After `serve --watch` prints
+> "Restarting server...", reload the page once more to see your change.
+
+`oriel serve` listens on `127.0.0.1`, on port 8000 or the one the `PORT` variable names. `--host` and `--port` choose
+others:
+
+```sh
+node oriel serve --watch --host=0.0.0.0 --port=3000
+```
+
+The API kit has no Vite config and no `dev` script: `node oriel serve --watch` is all it needs. An app made with Bun
+runs `bun run dev` and `bun oriel serve --watch`.
+
+If you passed `--no-install`, the printed commands start with the steps the installer skipped: `npm install`,
+`node oriel key:generate`, `node oriel migrate` and `npm run build`.
+
+> [!TIP]
+> Every command the framework knows is listed by `node oriel list`, and `node oriel help <command>` explains one.
+
+## Initial configuration
+
+Your app's settings are in the `config` folder, one file per part of the framework: `config/app.ts`,
+`config/database.ts`, `config/session.ts` and so on. A new app runs as it is, but you may want to look at
+`config/app.ts`, which holds the app's name, URL and locale.
+
+### Environment based configuration
+
+The values that differ between your machine and your servers, such as the database's password or the mail server,
+come from the `.env` file at the root of your app, which the config files read with `env()`. The installer writes
+`.env` for you, and git ignores it: each machine has its own, and its secrets stay out of your repository.
+[Configuration](configuration.md) explains the file and `env()`.
+
+### Databases and migrations
+
+A new app uses SQLite, in `database/database.sqlite`, which the installer created and migrated. To use PostgreSQL or
+MySQL instead, install its driver, `pg` or `mysql2`:
+
+```sh
+npm install pg
+```
+
+then set the `DB_*` variables in `.env`:
+
+```dotenv
+DB_CONNECTION=pgsql
+DB_HOST=127.0.0.1
+DB_PORT=5432
+DB_DATABASE=blog
+DB_USERNAME=root
+DB_PASSWORD=
+```
+
+Create the database on your server, then run your migrations:
+
+```sh
+node oriel migrate
+```
+
+For MySQL, `DB_CONNECTION` is `mysql` and the port is usually 3306.
+
+## Editor support
+
+The OrielJS extension for VS Code covers the strings Oriel reads at run time, where TypeScript can't help: it completes
+validation rules, `config()` keys, `env()` names, view names, and the actions and properties in Live's `o:` attributes,
+shows their docs when you hover, and warns about one your app doesn't have. It also runs `route:types` and
+`inertia:types` again when your routes, controllers or pages change, and puts the `oriel` commands in the command
+palette. Install it from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=orieljs.orieljs),
+or search for OrielJS in the editor's Extensions view. It needs Oriel 0.1.0-alpha.9 or later, and reads your app only
+in a trusted workspace.
+
+## Next steps
+
+Read how an app is laid out in [Directory structure](structure.md), and how it reads its settings in
+[Configuration](configuration.md). Your app's routes live in `routes/web.ts`: [Routing](routing.md) is the place to
+start writing your own code. When a request has slow work to do, such as sending mail or resizing images, hand it to a
+worker with [Queues](queues.md). When your app is ready to go live, [Deployment](deployment.md) covers building and
+running it on a server.
+
+To learn how an app runs, read [Request lifecycle](lifecycle.md), [Service container](container.md) and
+[Facades](facades.md).

package/docs/lifecycle.md

@@ -0,0 +1,234 @@
+# Request lifecycle
+
+Oriel builds your app once, when its process starts, and answers every request from it, until the process ends and
+the app shuts down.
+
+## Introduction
+
+You can build an app without knowing how Oriel works inside. Knowing the order in which it does things tells you
+where your own code goes: what a service provider can rely on, when your routes exist, and what lasts longer than one
+request.
+
+## Lifecycle overview
+
+### First steps
+
+Your app has two entry points. `public/index.ts` starts the web server, as `node --import tsx public/index.ts` or
+`bun public/index.ts`, and `node oriel serve` starts the same server while you work. The `oriel` file runs a command,
+as `node oriel migrate`. Both get the application from `createApplication()` in `bootstrap/app.ts`:
+
+```ts title="public/index.ts"
+// @filename: bootstrap/app.ts
+export declare function createApplication(): Promise<import('@orieljs/framework').Application>
+// ---cut---
+import { serve } from '@orieljs/framework'
+import { createApplication } from '../bootstrap/app'
+
+// Production entry: `node --import tsx public/index.ts`, or `bun public/index.ts`.
+await serve(await createApplication())
+```
+
+`Application.configure()` creates the application, which is also the [service container](container.md). The methods
+after it record what you give them, and `create()` puts the app together:
+
+```ts title="bootstrap/app.ts"
+import { dirname } from 'node:path'
+import { Application } from '@orieljs/framework'
+import providers from './providers'
+
+/** Builds the application. Each call returns a fresh app (tests need one per test). */
+export function createApplication(): Promise<Application> {
+  return Application.configure({ basePath: dirname(import.meta.dirname) })
+    .withRouting({ web: 'routes/web.ts', console: 'routes/console.ts', health: '/up' })
+    .withProviders(providers)
+    .create()
+}
+```
+
+`create()` loads your `.env` file and every file in `config/` ([Configuration](configuration.md) covers both), then
+registers the service providers. Each call makes a new application, so your tests can have a fresh one for every test.
+
+### HTTP / console kernels
+
+A request goes to the HTTP kernel, and a command to the console kernel.
+
+`serve()` answers a `GET` or `HEAD` request for a file in `public/` itself, and hands every other request to
+`app.handle()`, which passes it to the HTTP kernel and returns the response. The kernel takes a web-standard `Request`
+and returns a `Response`: think of it as a black box that stands for your whole app. It wraps the request in Oriel's
+request object, applies the trusted proxies and the body limits of `config/http.ts` (see
+[Requests](requests.md#body-size-limits)), reads the body, and sends the request through the global middleware to the
+router.
+
+`node oriel` gives its arguments to the console kernel. The command runs, the app terminates as it does after a
+request, then it shuts down, and the process exits with the command's exit code.
+
+### Service providers
+
+Service providers set up every part of the framework: the database, the queue, validation, routing and the rest.
+`create()` calls each provider's `register()`, in order. The framework has 22, registered first, in this order:
+Pipeline, Encryption, Cookie, Session, Hashing, Log, Event, Cache, Filesystem, Database, Queue, Bus, Mail,
+Notifications, Validation, Auth, View, Inertia, Live, Routing, Http and Console (each one's class is its name followed
+by `ServiceProvider`). Each may rely on the ones before it. Yours come next, in the order `bootstrap/providers.ts`
+lists them.
+
+`create()` registers the providers but doesn't boot them. The app boots once, the first time something needs it:
+`serve()` before it starts listening, `node oriel` before it runs its command, your tests before each test, or the
+first request the app handles. Booting runs, in this order:
+
+1. the `booting()` callbacks;
+2. each provider's `boot()`, in the order they were registered. A provider registered while the app boots is booted in
+   the same pass, and one registered after it has booted is booted at once;
+3. the `booted()` callbacks, in the order they were added: those you give the builder first, then the framework's,
+   which add the health route, load the route files of `withRouting()` (the `web` files in the `web` group, then the
+   `api` files in the `api` group), apply your `withMiddleware()` callback and, in the console only, find your
+   commands; last, those your providers add in `boot()`.
+
+Your route files run once every provider has booted, so a route pattern, a binding or a gate that a provider sets up
+in `boot()` is ready for them. The builder takes callbacks of its own:
+
+```ts
+Application.configure({ basePath: '.' })
+  .booting((app) => {
+    // Before the first provider boots...
+  })
+  .booted((app) => {
+    // Once every provider has booted, before your routes load...
+  })
+```
+
+> [!NOTE]
+> Laravel bootstraps the application again for every request: a PHP process handles one request, then forgets it.
+> An Oriel app runs in a long-lived Node or Bun process, so it registers and boots its providers once, and serves
+> every request from the same application. A singleton lasts as long as the process; what belongs to one request lives
+> in that request's [scope](container.md#request-scopes).
+
+### Routing
+
+`app.handle()` opens a request scope, and the kernel binds the request in it: everything resolved for this request,
+such as the request, its session and its cookie jar, lives in the scope and is dropped with it. The global middleware
+run first: `TrimStrings`, `ConvertEmptyStringsToNull`, and those you add with
+[`withMiddleware()`](middleware.md#global-middleware).
+
+The router then finds the route. A path no route matches is a 404, and a path whose routes don't take the request's
+method is a 405 with an `Allow` header. The router records the route as the current one, then runs the route's
+middleware: those of its groups, outer group first, then its own. The routes in `routes/web.ts` are in the `web` group,
+which gives them their cookies, their session and CSRF protection:
+
+| The `web` group | What it does |
+| --- | --- |
+| `EncryptCookies` | Decrypts the request's cookies and encrypts the response's |
+| `AddQueuedCookiesToResponse` | Adds the cookies queued on the cookie jar to the response |
+| `StartSession` | Loads the session, and saves it once the response is ready |
+| `VerifyCsrfToken` | Refuses a form without the CSRF token |
+
+The `web` and `api` groups' middleware, `auth` and `guest` run before the route's other middleware, then route model
+binding replaces the parameters that name a model, then the rest run ([Sorting
+middleware](middleware.md#sorting-middleware) has the rule). Last, the action runs: a closure is called with the
+route's parameters, in URI order, and a controller is built by the container for this request. Whatever the action
+returns becomes the response, as [Responses](responses.md) describes.
+
+### Finishing up
+
+The response goes back out through the route's middleware, then the global middleware, each of which can examine or
+change it. An error thrown at any stage becomes a response at that stage, rendered by the exception handler (see
+[Error handling](errors.md)), so a middleware further out always receives a response. The response to a `HEAD`
+request loses its body here.
+
+The server writes the response, and then the app terminates the request, still inside its scope:
+
+1. `terminate()` runs on each [terminable middleware](middleware.md#terminable-middleware), the global ones first,
+   then the route's;
+2. the `terminating()` callbacks run, in the order they were added. One of them is the framework's: it runs the jobs
+   you dispatched with [`dispatchAfterResponse()`](queues.md#running-a-job-now).
+
+On Node, this starts once the response is written; on Bun, right after the response is handed to the server.
+
+Register a terminating callback in a service provider. It receives no arguments:
+
+```ts title="app/Providers/AppServiceProvider.ts"
+// @filename: app/Services/Metrics.ts
+export declare class Metrics {
+  flush(): Promise<void>
+}
+// ---cut---
+import { ServiceProvider } from '@orieljs/framework'
+import { Metrics } from '../Services/Metrics'
+
+export class AppServiceProvider extends ServiceProvider {
+  override register(): void {
+    this.app.singleton(Metrics)
+  }
+
+  override boot(): void {
+    this.app.terminating(async () => {
+      await this.app.make(Metrics).flush()
+    })
+  }
+}
+```
+
+> [!WARNING]
+> The terminating callbacks also run after each `node oriel` command, and after the server sends a file from
+> `public/`, which never reaches the app. They then run outside any request, where `request()` throws. A terminating
+> callback that throws stops the ones after it, and its error is printed to the console rather than reported; after a
+> command, `node oriel` then exits with code 1.
+
+## Shutting down
+
+A Node or Bun process keeps its database pools, its Redis clients and its log files open from one request to the next.
+When the process ends, `app.shutdown()` closes them: it runs the callbacks registered with `app.onShutdown()`, once.
+
+- The server calls it when it receives `SIGINT` or `SIGTERM`. It stops taking new connections, waits for the requests
+  in flight (closing the connections that are still open after 10 seconds), shuts the app down, and exits with 0.
+- `node oriel` calls it after its command, also when the command throws.
+- A script that makes the app itself must call it before it exits, or the last log entries are lost (see [Flushing
+  the log](logging.md#flushing-the-log)).
+
+The callbacks run newest first. Yours were registered after the framework's, so they run before the framework closes
+what they might use. Then the framework closes the queue's Redis connections, the database pools, the cache's Redis
+clients, the log files (writing out what is waiting) and the session's Redis connection, each only if your app opened
+it:
+
+```ts title="app/Providers/AppServiceProvider.ts"
+// @filename: app/Services/Metrics.ts
+export declare class Metrics {
+  close(): Promise<void>
+}
+// ---cut---
+import { ServiceProvider } from '@orieljs/framework'
+import { Metrics } from '../Services/Metrics'
+
+export class AppServiceProvider extends ServiceProvider {
+  override register(): void {
+    this.app.singleton(Metrics)
+
+    this.app.onShutdown(async () => {
+      if (this.app.resolved(Metrics)) await this.app.make(Metrics).close()
+    })
+  }
+}
+```
+
+A callback that throws is printed with `console.error`, and the others still run. If the callbacks haven't finished
+after 10 seconds, the rest are given up on, with "The shutdown callbacks did not finish within 10 seconds; carrying on
+with the exit.", so the process can still exit. `shutdown()` never rejects, and calling it again returns the same
+promise.
+
+| | `terminating()` | `onShutdown()` |
+| --- | --- | --- |
+| Runs | After each response, and after each `node oriel` command | Once, when the process ends |
+| Inside | The request's scope, after a request | No request |
+| Order | The order they were added | Newest first |
+| For | Work that waits until the response is sent | Closing pools, clients and files |
+
+> [!NOTE]
+> Laravel has no `onShutdown()`: PHP frees what a request opened when the request ends. An Oriel process serves many
+> requests, so the handles it opens stay open until the process ends, and `shutdown()` closes them before it exits.
+
+## Focus on service providers
+
+Service providers are the key to how an Oriel app starts: the application is created, the providers are registered and
+booted, and the requests are handed to the booted app. Your own providers live in `app/Providers`. A new app's
+`AppServiceProvider` is empty: it is the place for your app's bindings and its setup at boot. A larger app can split
+them over several providers, each listed in `bootstrap/providers.ts`. [Service providers](providers.md) explains how
+to write them.

package/docs/live-tests.md

@@ -0,0 +1,226 @@
+# Live tests
+
+`Live.test()` mounts a Live component in a test, calls its actions and checks its state and HTML. It goes through the
+same steps as the browser's updates, without a browser.
+
+## Creating your first test
+
+`make:live --test` writes a test with the component:
+
+```sh
+node oriel make:live Counter --test
+```
+
+The test, in `tests/Feature/Live`, mounts the component and checks its HTML:
+
+```ts title="tests/Feature/Live/Counter.test.ts"
+// @filename: app/Live/Counter.tsx
+import { Component } from '@orieljs/framework'
+export default class Counter extends Component {
+  count = 0
+  increment() {
+    this.count++
+  }
+  render() {
+    return <div>{this.count}</div>
+  }
+}
+// ---cut---
+import { Live } from '@orieljs/framework'
+import { expect, test } from 'vitest'
+import Counter from '../../../app/Live/Counter'
+import { TestCase } from '../../TestCase'
+
+TestCase.boot()
+
+test('counter renders', async () => {
+  const component = await Live.test(Counter)
+  expect(component.html()).toContain('<div')
+})
+```
+
+`Live.test()` needs the test's application, so boot the test case in the file.
+
+## Testing actions and properties
+
+`set()` sets a property, as an `o:model` input does, and `call()` calls an action, as `o:click` does. Both send an
+update, so `await` each one; the assertions that follow are synchronous and chain:
+
+```ts title="tests/Feature/Live/Counter.test.ts"
+// @filename: app/Live/Counter.tsx
+import { Component } from '@orieljs/framework'
+export default class Counter extends Component {
+  count = 0
+  increment() {
+    this.count++
+  }
+  render() {
+    return <div>{this.count}</div>
+  }
+}
+// ---cut---
+import { Live } from '@orieljs/framework'
+import { test } from 'vitest'
+import Counter from '../../../app/Live/Counter'
+import { TestCase } from '../../TestCase'
+
+TestCase.boot()
+
+test('the counter goes up', async () => {
+  const component = await Live.test(Counter)
+
+  await component.set('count', 5)
+  await component.call('increment')
+
+  component.assertSet('count', 6).assertSee('6')
+})
+```
+
+`set()` also takes several properties at once, `set({ title: 'Hello', body: 'World' })`, and `call()` the action's
+arguments after its name: `call('delete', 5)`. `toggle('open')` flips a boolean, `refresh()` renders the component
+again, and `dispatch('post-created', { id: 1 })` sends it an event, which its `@On` methods receive.
+
+The second argument of `Live.test()` is the mount parameters, as `<Live>` props would be:
+
+```ts
+// @filename: app/Live/Counter.tsx
+import { Component } from '@orieljs/framework'
+export default class Counter extends Component {
+  count = 0
+  render() {
+    return <div>{this.count}</div>
+  }
+}
+// ---cut---
+import Counter from './app/Live/Counter'
+
+const component = await Live.test(Counter, { count: 4 })
+```
+
+`get('count')` reads a property, `html()` the last HTML, `instance()` the component itself, and `effects()` what the
+last update asks of the browser, such as a redirect.
+
+### Authenticating
+
+`Live.test()` runs in the test's requests, so a user you gave `actingAs()` is signed in for the component:
+
+```ts title="tests/Feature/Live/Password.test.ts"
+// @filename: app/Live/Settings/Password.tsx
+import { Component } from '@orieljs/framework'
+export default class Password extends Component {
+  current_password = ''
+  password = ''
+  password_confirmation = ''
+  updatePassword() {}
+  render() {
+    return <form />
+  }
+}
+// ---cut---
+import { Hash, Live } from '@orieljs/framework'
+import { RefreshDatabase } from '@orieljs/framework/testing'
+import { expect, test } from 'vitest'
+import Password from '../../../app/Live/Settings/Password'
+import { User } from '../../../app/Models/User'
+import { TestCase } from '../../TestCase'
+
+const t = TestCase.boot({ uses: [RefreshDatabase] })
+
+test('password can be updated', async () => {
+  const user = await User.factory().create()
+
+  t.actingAs(user)
+  const component = await Live.test(Password)
+  await component.set({ current_password: 'password', password: 'new-password', password_confirmation: 'new-password' })
+  await component.call('updatePassword')
+
+  component.assertHasNoErrors().assertSet('password', '').assertDispatched('password-updated')
+
+  expect(await Hash.check('new-password', (await user.fresh())!.password)).toBe(true)
+})
+```
+
+What the component changes in the session, such as a sign-in, carries on to the test's next request, and the
+other way round.
+
+## Testing validation
+
+A failed validation leaves its errors on the component, which `assertHasErrors()` checks:
+
+```ts
+import type { Testable } from '@orieljs/framework/testing'
+declare const component: Testable
+// ---cut---
+await component.set('title', '')
+await component.call('save')
+
+component.assertHasErrors(['title'])
+```
+
+With no keys, `assertHasErrors()` passes when there is any error, and `assertHasNoErrors()` when there is none.
+`instance().errors.first('title')` reads a message.
+
+## Testing authorization
+
+An action that calls `abort(403)`, or whose policy check fails, throws in the test as it would end the request:
+
+```ts
+import type { Testable } from '@orieljs/framework/testing'
+import { expect } from 'vitest'
+declare const component: Testable
+// ---cut---
+await expect(component.call('delete', 5)).rejects.toMatchObject({ status: 403 })
+```
+
+A page route's `can` middleware runs on the page's own request, so check it with an [HTTP test](http-tests.md) of the
+page.
+
+## Testing redirects and events
+
+```ts
+import type { Testable } from '@orieljs/framework/testing'
+declare const component: Testable
+// ---cut---
+await component.call('save')
+
+component.assertRedirect('/posts').assertDispatched('post-created', { title: 'Hello' })
+```
+
+`assertRedirect()` with no URL passes on any redirect. `effects().redirectUsingNavigate` is `true` when the action
+asked for `{ navigate: true }`.
+
+## Testing file uploads
+
+In a `WithFileUploads` component, `set()` with a `FakeFile` uploads it as the browser would: through the upload rules,
+to the temporary disk, and into the property as a `TemporaryUploadedFile`:
+
+```ts
+import { FakeFile, type Testable } from '@orieljs/framework/testing'
+declare const component: Testable
+// ---cut---
+await component.set('photo', FakeFile.image('photo.jpg'))
+await component.call('save')
+
+component.assertHasNoErrors()
+```
+
+An array of files sets a `multiple` input's property. A file that fails `live.temporary_file_upload.rules` leaves the
+upload's error on the property. Use `Storage.fake()` to check where `store()` puts the file.
+
+## Available assertions
+
+| Assertion | Passes when |
+| --- | --- |
+| `assertSet(name, value)`, `assertNotSet(name, value)` | The property has the value, or hasn't |
+| `assertSee(...texts)`, `assertDontSee(...texts)` | The HTML has each text, escaped as the HTML writes it |
+| `assertSeeHtml(...html)` | The HTML has each piece of HTML, as it is |
+| `assertSeeText(...texts)`, `assertDontSeeText(...texts)` | The text, with the tags taken out, has each text |
+| `assertHasErrors(keys?)`, `assertHasNoErrors(keys?)` | The component has errors for the keys, or has none |
+| `assertDispatched(name, params?)`, `assertNotDispatched(name)` | The last update dispatched the event, with those parameters |
+| `assertRedirect(url?)`, `assertNoRedirect()` | The last update redirects, to that URL |
+| `assertReturned(value)` | The last action returned the value |
+
+> [!NOTE]
+> Livewire's `assertSeeLivewire()`, `assertViewHas()`, `assertCount()` and `withQueryParams()` aren't in Oriel. To
+> check that a page has a component, check the page's HTML with an HTTP test; `get()` and Vitest's `expect()` check
+> the rest.