Skip to content
GitHub

Strutvane 0.2 is still being built. These pages describe how it will work; anything marked "Coming in 0.2" doesn't exist yet. Release notes and support policy.

HTTP Tests

View as Markdownllms.txt

An HTTP test (a feature test) sends a request to one of your routes and checks the response, exactly as a browser or another program would see it: the status code, the JSON body, the headers. It goes through everything: middleware, CSRF, validation, policies, the database. If an HTTP test passes, the feature works.

Requests go straight into your app in the same process: no server, no port, no network. A typical test takes a few milliseconds.

tests/feature/posts.test.ts
import { randomBytes } from 'node:crypto'
import { beforeEach, it } from 'vitest'
import type { Application } from '@strutvane/framework'
import { client, refreshDatabase } from '@strutvane/framework/testing'
import { createApp } from '../../bootstrap/app.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)
})
it('lists posts', async () => {
const response = await client(app).getJson('/api/posts')
response.assertStatus(200).assertJsonPath('meta.total', 0)
})

What you’ll see:

✓ tests/feature/posts.test.ts (1 test) 18ms

client(app) gives you a request builder for one app:

Method Sends
getJson(path) GET with Accept: application/json
postJson(path, body) POST with a JSON body
putJson(path, body) PUT with a JSON body
patchJson(path, body) PATCH with a JSON body
deleteJson(path) DELETE
get(path) GET as a browser would (Accept: text/html), for web routes
send(method, path, body) any method; a string body is sent as-is

Paths include the query string:

await client(app).getJson('/api/posts?filter[status]=published&sort=-created_at&search=hello')

Each request comes from the address 203.0.113.10, so rate limits and IP rules behave as for a real visitor.

withToken() sends Authorization: Bearer <token> (proven in the prototype under the name actingAs()):

const asAlice = client(app).withToken(demoTokens.alice)
await asAlice.postJson('/api/posts', { title: 'My second post' })

The client is immutable: client(app) is still a guest after that line. Keep asAlice around to make several requests as Alice.

const alice = await User.factory().create()
await client(app).actingAs(alice).asTenant(acme).postJson('/api/projects', { name: 'Launch' })
await client(app).withHeaders({ 'accept-language': 'fr', 'if-match': '"v3"' }).patchJson('/api/posts/hello-world', { title: 'Bonjour' })

Every response is a TestResponse. Assertions return the response, so you can chain them:

Assertion Fails unless…
assertStatus(code) the status is exactly code
assertJsonPath(path, value) the value at a dot path equals value (deep equality)
assertProblem(status, code) it’s application/problem+json with that status and code

And for your own checks:

Property What it is
status the status code
headers a Headers object
text the raw body
json the body parsed as JSON
path('data.0.title') the value at a dot path
tests/feature/posts.test.ts
import { expect, it } from 'vitest'
it('sorts newest first', async () => {
const response = await client(app).getJson('/api/posts?sort=-created_at')
response.assertStatus(200)
const titles = (response.path('data') as Array<{ title: string }>).map((post) => post.title)
expect(titles).toEqual(['Third', 'Second', 'First'])
expect(response.headers.get('content-type')).toContain('application/json')
})

Dot paths use numbers for list items: data.0.title is the first post’s title.

Every failure message includes the body (the first 2,000 characters), so a failing test explains itself:

Error: Expected status 201, got 422. Body: {"type":"about:blank","title":"Validation failed","status":422,"code":"validation_failed","issues":[{"path":["title"],"field":"title","code":"too_short","message":"Title must be at least 3 characters long."}]}
Error: Expected meta.total to be 3, got 2. Body: {"data":[…],"meta":{"total":2,…}}
Error: Expected problem+json, got text/html.
it('creates a post and points at it', async () => {
const response = await client(app).withToken(demoTokens.alice).postJson('/api/posts', { title: 'Hello world' })
response.assertStatus(201).assertJsonPath('data.slug', 'hello-world')
expect(response.headers.get('location')).toBe('/api/posts/hello-world')
})
it('needs a title', async () => {
const response = await client(app).withToken(demoTokens.alice).postJson('/api/posts', { body: 'No title' })
response.assertProblem(422, 'validation_failed')
expect(response.path('issues')).toContainEqual(expect.objectContaining({ path: ['title'], field: 'title', code: 'required' }))
})
it('refuses fields that are not fillable', async () => {
const response = await client(app).withToken(demoTokens.alice).postJson('/api/posts', { title: 'Hi there', author_id: 99 })
response.assertProblem(422, 'validation_failed').assertJsonPath('issues.0', {
path: ['author_id'],
field: 'author_id',
code: 'unknown_field',
message: '"author_id" is not a field you can send here. Remove it from the request body.',
})
})

A client can’t set author_id (it’s set from the signed-in user), so it can’t post as someone else. Test this for every field that must come from the server.

it('hides drafts as missing, and refuses changes others can see', async () => {
;(await client(app).withToken(demoTokens.bob).getJson('/api/posts/alice-draft')).assertStatus(404)
;(await client(app).withToken(demoTokens.bob).patchJson('/api/posts/hello-world', { title: 'Mine now' })).assertProblem(403, 'forbidden')
})

Testing the 404 matters: it proves Bob can’t even learn that Alice’s draft exists. See Authorization.

it('asks guests to sign in', async () => {
;(await client(app).postJson('/api/posts', { title: 'Hello' })).assertProblem(401, 'unauthenticated')
})
Section titled “CSRF: a cookie request without a token is refused”

Real browsers send a session cookie. A test can check that a forged form post is refused:

it('refuses a cross-site cookie request', async () => {
const response = await client(app)
.withHeaders({ cookie: 'strutvane_session=abc', origin: 'https://evil.example' })
.postJson('/api/posts', { title: 'Hello' })
response.assertProblem(419, 'csrf_token_mismatch')
})

When a test isn’t about CSRF but uses a cookie, skip the check for that client only:

await client(app).withHeaders({ cookie: 'strutvane_session=abc' }).withoutCsrf().postJson('/api/posts', { title: 'Hello' })

withoutCsrf() is not a header: nothing a real client sends can switch CSRF off. It only works when APP_ENV=testing; the app refuses the request in any other environment.

it('throttles after 120 requests a minute', async () => {
for (let i = 0; i < 120; i++) await client(app).getJson('/api/posts')
const response = await client(app).getJson('/api/posts')
response.assertStatus(429)
expect(Number(response.headers.get('retry-after'))).toBeGreaterThan(0)
})
it('serves the React shell', async () => {
const response = await client(app).get('/posts')
response.assertStatus(200)
expect(response.text).toContain('<div id="root">')
})

With teams, test isolation from the attacker’s side. Generated attack tests do this for every resource; write the same for your custom routes:

it('never shows another team its projects', async () => {
const asAcme = client(app).actingAs(acmeUser).asTenant(acme) // planned API, see above
const asGlobex = client(app).actingAs(globexUser).asTenant(globex)
const created = await asAcme.postJson('/api/projects', { name: 'Secret launch' })
const id = created.path('data.id') as string
;(await asGlobex.getJson(`/api/projects/${id}`)).assertStatus(404)
;(await asGlobex.getJson('/api/projects?search=Secret')).assertJsonPath('meta.total', 0)
;(await asGlobex.deleteJson(`/api/projects/${id}`)).assertStatus(404)
})

HTTP tests never open a port, so they behave the same on Windows, macOS and Linux, with or without Docker. In Docker mode, npm test runs inside the app container next to the test database. The only difference is the database engine: use the same engine as production (see Database Testing).

Expected 200, got 404 for a post I just created

Section titled “Expected 200, got 404 for a post I just created”

Why: the route binds by slug (/api/posts/{post:slug}) and you used the id, or the post isn’t visible to the user making the request, which looks like a 404 on purpose. Fix: request by slug, and check the policy’s view() for that user.

Error: Expected status 201, got 419. Body: {…"code":"csrf_token_mismatch"…}

Why: the request carries a session cookie, so CSRF applies. Fix: use a bearer token (withToken()), or .withoutCsrf() on that client.

withToken didn’t stick for my second request

Section titled “withToken didn’t stick for my second request”

Why: the client is immutable. client(app).withToken(t) returns a new client; calling client(app) again gives a guest. Fix: keep the returned client: const asAlice = client(app).withToken(t).

assertJsonPath('data.title', …) gets undefined

Section titled “assertJsonPath('data.title', …) gets undefined”

Why: data is a list on index routes. The first item is data.0. Fix: assertJsonPath('data.0.title', 'Hello').

The 422 body is right but assertProblem fails

Section titled “The 422 body is right but assertProblem fails”
Error: Expected problem+json, got application/json.

Why: your controller built its own JSON error instead of throwing a framework error. Fix: throw ValidationError, ForbiddenError or HttpError, so every error has the same shape.