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.

Mocking

View as Markdownllms.txt

Some things your code does shouldn’t really happen in a test: sending mail to a customer, charging a card, calling a partner’s API, waiting a week for a link to expire. Mocking means swapping the real thing for a stand-in during the test. A fake is a stand-in that records what your code asked of it, so you can check it afterwards: “a welcome mail was sent to Asha”, “nothing called the internet”.

Strutvane is built for this: services come from the app’s container (a registry of the app’s services), so a test can replace any of them for that test’s app only, without touching global state.

Everything in the app that asks “what time is it?” through now() reads the clock service. Replace it, and time stands still:

tests/feature/report-date.test.ts
import { ClockToken } from '@strutvane/framework'
import { client } from '@strutvane/framework/testing'
import { expect, it } from 'vitest'
it('stamps the report with today', async () => {
app.container.instance(ClockToken, () => new Date('2026-11-15T10:00:00Z'))
const response = await client(app).withToken(demoTokens.alice).postJson('/api/reports', {})
expect(response.path('data.generated_at')).toBe('2026-11-15T10:00:00.000Z')
})

What you’ll see:

✓ tests/feature/report-date.test.ts (1 test) 9ms

The test is now the same tomorrow as today. Use now() instead of new Date() in app code so the clock can be swapped.

Everything registered in the container can be replaced with app.container.instance(token, value), before the code that uses it runs:

tests/feature/exchange-rate.test.ts
import { it, expect } from 'vitest'
import { client } from '@strutvane/framework/testing'
import { RatesToken, type Rates } from '../../app/services/rates.ts'
it('converts with the partner rate', async () => {
const fixedRates: Rates = { rate: async () => 1.08 } // a hand-written stand-in
app.container.instance(RatesToken, fixedRates)
const response = await client(app).getJson('/api/prices/42?currency=USD')
response.assertStatus(200).assertJsonPath('data.price', '108.00')
})

This works because your controller asks the container for RatesToken (with static inject) instead of creating the service itself. That’s the main reason Strutvane uses injection: anything injected can be swapped in a test. See Service Container.

Container method Use in tests for
instance(token, value) “use exactly this object” (the usual choice)
singleton(token, factory) “build it once, lazily”
bind(token, factory) “build a new one every time”
has(token) checking whether something is registered
import { freezeTime, travel, travelTo } from '@strutvane/framework/testing'
freezeTime(app) // now() stops at the current moment
travelTo(app, new Date('2026-12-01T00:00:00Z')) // jump to a date
travel(app, { minutes: 61 }) // move forward: an hour-long link is now expired

A typical use is expiry:

it('expires a temporary download link after 10 minutes', async () => {
freezeTime(app)
const link = await app.run(() => url.temporarySignedRoute('downloads.show', new Date(Date.now() + 10 * 60_000), { file }))
travel(app, { minutes: 11 })
;(await client(app).get(link)).assertProblem(403, 'signature_expired')
})

Your code may call other services: a payment provider, an exchange-rate API, a webhook. In tests, those calls must never reach the internet: they’d be slow, flaky, and could change real data.

tests/feature/rates.test.ts
import { Http } from '@strutvane/framework'
import { client } from '@strutvane/framework/testing'
import { it } from 'vitest'
it('reads the rate from the partner', async () => {
await app.run(async () => {
Http.preventStrayRequests() // any call without a fake fails the test
Http.fake({ 'https://rates.example.com/*': { status: 200, body: { rate: 1.08 } } })
;(await client(app).getJson('/api/prices/42?currency=USD')).assertJsonPath('data.price', '108.00')
Http.assertSent((request) => request.url.startsWith('https://rates.example.com/'))
})
})

What you’ll see: the test passes without network access. If your code calls an address you didn’t fake, the test fails loudly instead of quietly calling a real server, something like:

StrayRequestError: GET https://api.other.example/v1 was not faked, and stray requests are prevented.

Test what happens when the partner is down:

Http.fake({ 'https://rates.example.com/*': { status: 503, body: 'Service Unavailable' } })
;(await client(app).getJson('/api/prices/42?currency=USD')).assertProblem(502, 'upstream_unavailable')

The status and code your app answers are yours to choose; the point is that the test proves you handle it.

The SSRF-safe client (safeFetch) already takes a resolver for tests, so you can prove your code refuses internal addresses without a real DNS lookup:

import { HttpClientError, safeFetch } from '@strutvane/framework'
import { expect, it } from 'vitest'
it('refuses a webhook URL that points at the cloud metadata service', async () => {
const resolver = async () => ['169.254.169.254'] // the name "resolves" to a metadata address
await expect(safeFetch('https://hooks.example.com/x', { resolver })).rejects.toMatchObject({ code: 'ssrf_blocked' })
})

ssrf_blocked means nothing was sent at all. See HTTP Client.

import { Mail } from '@strutvane/framework'
await app.run(async () => {
Mail.fake()
await client(app).postJson('/register', { name: 'Asha', email: 'asha@example.test', password: 'a long sentence I can remember 42' })
Mail.assertSent('WelcomeMail', (mail) => mail.to === 'asha@example.test')
Mail.assertNothingSent() // or this, to prove no mail went out
})

Mail.fake() is part of the 0.2 testing kit. See Mail.

Queues, events, notifications, storage and processes

Section titled “Queues, events, notifications, storage and processes”

These fakes arrive with their features in 0.3. They all work the same way: call .fake(), run your code, then assert.

Fake Asserts (Laravel’s names) Page
Queue.fake() assertPushed(Job), assertNotPushed(Job), assertNothingPushed() Queues
Event.fake() assertEmitted('post.published'), assertNotEmitted(…) Events
Notification.fake() assertSentTo(user, Notification), assertNotSentTo(…) Notifications
Storage.fake('local') a temporary disk; check files with exists() File Storage
Process.fake({...}) assertRan([...]) Processes
Queue.fake()
await client(app).withToken(demoTokens.alice).postJson('/api/exports', {})
Queue.assertPushed(ExportPosts)

Faking a queue means jobs are recorded, not run. Test the job itself separately, by calling it directly.

For your own modules that aren’t in the container, Vitest’s vi.fn() and vi.spyOn() work as usual:

import { vi } from 'vitest'
import * as slugs from '../../app/support/slugs.ts'
vi.spyOn(slugs, 'randomSuffix').mockReturnValue('ab12')

Prefer the container when you can: a swapped container service is undone automatically when the next test builds a fresh app, while vi.spyOn must be restored (vi.restoreAllMocks() in afterEach).

Fakes are per app, so tests stay independent

Section titled “Fakes are per app, so tests stay independent”

Each test builds its own app (createApp() in beforeEach), and fakes live in that app’s container. Two test files running in parallel never see each other’s fakes, and a fake never leaks into the next test. This is why the accessors read the current app instead of a global.

Fakes are plain in-process objects: they behave the same on Windows, macOS and Linux, and with or without Docker. One difference matters: in Docker mode, a test that accidentally makes a real HTTP call goes out through the container’s network. Http.preventStrayRequests() catches that in both modes.

“Mail.fake() was called outside a request or console command”

Section titled ““Mail.fake() was called outside a request or console command””
✖ Mail.fake() 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: accessors read the current app, and test code runs outside one. Fix: wrap the test body in await app.run(async () => { … }).

Why: the code created the service itself (new RatesClient()) instead of asking the container, or the swap happened after the service was already built and cached as a singleton. Fix: inject it with static inject = [RatesToken], and swap it before the first request in the test.

Why: the code uses new Date() instead of now(), so freezing the clock has no effect. Fix: use now() in app code, and freeze the clock in the test.

Why: Mail.fake() was called in another app (an app built in beforeAll, while the request went to the one from beforeEach). Fix: fake on the same app the request goes to, inside app.run().

Why: Queue.fake() records jobs instead of running them, on purpose. Fix: assert it was pushed, and test the job itself in its own test.