Testing: Getting Started
A test is a small program that uses your app and checks the result: “when Alice posts a title, the API answers 201 and the slug is my-first-post”. You run all of them with one command, before every commit and in CI, so you find out about a broken feature in seconds instead of from a customer.
Strutvane apps use Vitest, a fast test runner for TypeScript (the installer offers Vitest only in 0.2; generated tests never use node:test). Feature tests send requests straight into your app (no server, no port, no network) against a real database of the same kind you use in production. That makes them fast and trustworthy.
The smallest example
Section titled “The smallest example”A new app already has tests. Run them:
npm testWhat you’ll see (something like this):
✓ tests/feature/health.test.ts (1 test) 4ms ✓ tests/feature/posts.test.ts (3 tests) 61ms
Test Files 2 passed (2) Tests 4 passed (4) Duration 1.32sEvery line with a ✓ is a test file; the numbers are its tests and how long they took. If one fails, you see a ✗, the test’s name, and what was expected versus what happened.
Your first feature test
Section titled “Your first feature test”A feature test checks one thing a user can do, through the same HTTP routes the UI uses. Here’s a complete one for the posts API:
import { randomBytes } from 'node:crypto'import { beforeEach, describe, it } from 'vitest'import type { Application } from '@strutvane/framework'import { client, refreshDatabase, seed } from '@strutvane/framework/testing'import { createApp } from '../../bootstrap/app.ts'import { demoTokens } from '../../database/seeders/database.seeder.ts'
let app: Application
beforeEach(async () => { app = createApp({ APP_ENV: 'testing', APP_KEY: 'base64:' + randomBytes(32).toString('base64'), DB_CONNECTION: 'sqlite', DB_DATABASE: ':memory:' }) await refreshDatabase(app) await seed(app)})
describe('posts', () => { it('lists published posts for guests', async () => { ;(await client(app).getJson('/api/posts')).assertStatus(200).assertJsonPath('meta.total', 3) })
it('lets an author write a post', async () => { const response = await client(app).withToken(demoTokens.alice).postJson('/api/posts', { title: 'My second post' }) response.assertStatus(201).assertJsonPath('data.slug', 'my-second-post').assertJsonPath('data.status', 'draft') })
it('stops other authors from editing it', async () => { ;(await client(app).withToken(demoTokens.bob).patchJson('/api/posts/hello-world', { title: 'Mine now' })).assertProblem(403, 'forbidden') })})This is the prototype’s example-app test, written with the decided 0.2 names (the prototype calls withToken() actingAs(), and runs its seeder with new DatabaseSeeder().run(); seed(app) runs database/seeders/database.seeder.ts, a defineSeeder() file). Read it top to bottom:
createApp({...})builds a fresh app for each test, with test settings:APP_ENV=testingand an in-memory SQLite database.refreshDatabase(app)creates every table from the schema your migrations produce (in milliseconds, without replaying each migration).seed(app)runs the app’s seeders: three published posts, two authors, and an API token for each (demoTokens, exported by this example app’s seeder).client(app)sends requests directly into the app, and each response has assertions you can chain.
What you’ll see:
✓ tests/feature/posts.test.ts (3 tests) 61msThe leading ; before (await …) is only there because the line starts with a parenthesis; it stops JavaScript from joining it to the line above.
The kinds of tests
Section titled “The kinds of tests”| Kind | What it checks | Where | Speed | Page |
|---|---|---|---|---|
| Unit | one function or class, no app (a policy, a cast, a price calculation) | tests/unit/ |
microseconds | below |
| Feature (HTTP) | a route, end to end: validation, policies, database, response | tests/feature/ |
milliseconds | HTTP Tests |
| Database | what’s stored: rows, soft deletes, tenancy | tests/feature/ |
milliseconds | Database Testing |
| Console | a node strut command: questions, output, exit code |
tests/feature/ |
milliseconds | below |
| Browser | the real UI in a real browser | tests/browser/ |
seconds | Browser Tests |
Write mostly feature tests: they catch the most with the least code. Add unit tests for tricky logic, and a few browser tests for the paths that must never break (sign-in, checkout).
A unit test
Section titled “A unit test”import { allows } from '@strutvane/framework'import { expect, it } from 'vitest'import { PostPolicy } from '../../app/policies/post.policy.ts'import type { Post } from '../../app/models/post.ts'
it('hides drafts from other authors', async () => { const draft = { id: 10, status: 'draft', author_id: 1 } as unknown as Post expect(await allows(new PostPolicy(), 'view', { id: 2, is_admin: false }, draft)).toBe(false)})What you’ll see: ✓ tests/unit/post.policy.test.ts (1 test) 2ms.
Running tests
Section titled “Running tests”| Command | What it runs |
|---|---|
npm test |
every test once (node strut test, as in CI) |
npx vitest |
watch mode: re-runs the tests touched by each file you save |
npx vitest tests/feature/posts.test.ts |
one file |
npx vitest -t "lets an author" |
tests whose name contains that text |
npx vitest --coverage |
with a coverage report |
npm run test:e2e |
browser tests, once you set up Playwright (see Browser Tests) |
Test settings and the test database
Section titled “Test settings and the test database”Tests always run with APP_ENV=testing. That switches on a few test-only things:
- the test client may skip the CSRF check with
withoutCsrf()(it’s refused in every other environment); - error responses include the developer
hint; - mail goes nowhere real.
Your tests never touch your development data. The installer creates a separate test database next to your development one and writes its name to .env:
| Database | .env key |
Value |
|---|---|---|
| SQLite | DB_TEST_DATABASE |
database/testing.sqlite |
| MySQL or PostgreSQL | DB_TEST_DATABASE |
<app name>_test (created with the right grants by the Docker setup) |
In 0.2, each Vitest worker (Vitest runs files in parallel) gets its own copy of that database, and each test runs inside a transaction that is rolled back at the end. So tests never see each other’s rows and can run in parallel. See Database Testing.
Console tests
Section titled “Console tests”A console test runs a node strut command and checks its questions, output and exit code, Laravel’s expectsQuestion() style:
import { strut } from '@strutvane/framework/testing'import { it } from 'vitest'
it('asks for the model when none is given', async () => { await strut(app, 'make:policy') .expectsQuestion('Which model is this policy for?', 'Post') .expectsOutput('Created app/policies/post.policy.ts') .assertExitCode(0)})Tests you get for free
Section titled “Tests you get for free”When node strut migrate creates the API for a new table, it also writes owned test files for it (you can edit them; they’re never overwritten):
- feature tests: list, show, create, update, delete, validation errors, and denials per role;
- cross-tenant attack tests (with teams): team A tries to read, change, delete, search and count team B’s posts, and must get
404or an empty list every time; - security tests: CSRF refusal, mass assignment, and enumeration (a hidden post answers exactly like a missing one).
Platform and Docker differences
Section titled “Platform and Docker differences”-
Docker mode:
npm teston your computer is forwarded into theappcontainer, where the test database lives. You type the same command. -
Without Docker: tests run on your machine against the test database in
.env. -
Windows (PowerShell): setting a variable for one run looks different:
macOS / Linux:
Terminal window DB_CONNECTION=sqlite npm testWindows (PowerShell):
Terminal window $env:DB_CONNECTION='sqlite'; npm test -
CI: the generated GitHub Actions workflow (installer question 25) runs
npm teston every push. The framework’s own CI runs on real MySQL and PostgreSQL; do the same for your app by giving CI the same engine as production.
Common mistakes
Section titled “Common mistakes”A test fails with “Expected status 201, got 419”
Section titled “A test fails with “Expected status 201, got 419””Error: Expected status 201, got 419. Body: {"type":"about:blank","title":"Page expired","status":419,"code":"csrf_token_mismatch",…}Why: the request used a session cookie, so the CSRF check applies, as it does for a real browser.
Fix: use a bearer token (withToken(token)), or skip the check in this test only:
await client(app).withHeaders({ cookie: 'strutvane_session=abc' }).withoutCsrf().postJson('/api/posts', { title: 'Hi' })My tests pass alone but fail together
Section titled “My tests pass alone but fail together”Why: one test left rows, a fake or a changed setting behind that another test sees. Usually a shared app built once at the top of the file instead of in beforeEach.
Fix: build the app and refresh the database in beforeEach, as in the example above.
“was called outside a request or console command”
Section titled ““was called outside a request or console command””✖ route() was called outside a request or console command, so there is no current app.→ Call it from a controller, middleware or command, or wrap the code in app.run(() => …) (tests: await app.run(async () => …)).Why: helpers such as route(), config() and encrypt() need a current app, and test code runs outside one.
Fix: wrap the call: await app.run(async () => route('posts.show', { post })).
Tests touch my development data
Section titled “Tests touch my development data”Why: DB_TEST_DATABASE is missing from .env, or a test sets DB_DATABASE to the development file.
Fix: restore the key (DB_TEST_DATABASE=database/testing.sqlite, or <app>_test for a server) and never point tests at the development database.
npm test says “no test files found”
Section titled “npm test says “no test files found””Why: test files must end in .test.ts (browser tests: .spec.ts) and live under tests/.
Fix: rename posts.ts to posts.test.ts.
Next steps
Section titled “Next steps”- HTTP Tests: every request helper and assertion.
- Database Testing: factories, seeders and checking rows.
- Mocking: fakes for mail, HTTP and time.
- Browser Tests: testing the real UI.