Documentation / @zerotal/testing / index / TestApp

Class: TestApp

Defined in: testing/src/TestApp.ts:45

Constructors

Constructor

new TestApp(_app, _errors?): TestApp

Defined in: testing/src/TestApp.ts:60

Parameters

_app

Application

_errors?

TestExceptionHandler

Returns

TestApp

Accessors

port

Get Signature

get port(): number

Defined in: testing/src/TestApp.ts:70

Returns

number

baseUrl

Get Signature

get baseUrl(): string

Defined in: testing/src/TestApp.ts:75

Base URL for all requests, e.g. http://localhost:52340

Returns

string

app

Get Signature

get app(): Application

Defined in: testing/src/TestApp.ts:80

The underlying application, for resolving container bindings inside a test.

Returns

Application

Methods

actingAs()

actingAs(user): this

Defined in: testing/src/TestApp.ts:98

Forge a signed session cookie containing user_id so subsequent requests behave as if the given user is authenticated via AuthMiddleware.

Reads session.secret and session.cookie from the container config. Chainable — returns this so you can inline it: await app.actingAs(user).get('/profile')

Parameters

user

id

string | number

Returns

this

Example

const res = await app.actingAs(user).get('/profile');
res.assertStatus(200);

actingAsGuest()

actingAsGuest(): this

Defined in: testing/src/TestApp.ts:108

Clear any auth cookie set by actingAs()/withSession(). Subsequent requests are guest. Call in afterEach to reset state between tests.

Returns

this

withSession()

withSession(data): this

Defined in: testing/src/TestApp.ts:122

Pre-seed session data for the next request, merged with any actingAs() user. Encoded into a real cookie by the app's session driver on the next request.

Parameters

data

Record<string, unknown>

Returns

this

Example

const res = await app.withSession({ locale: 'fr', flash_status: 'saved' }).get('/profile');

followingRedirects()

followingRedirects(): this

Defined in: testing/src/TestApp.ts:136

Enable automatic redirect following for all requests on this instance. The test client will follow up to 10 Location redirects transparently.

Returns

this

Example

const res = await app.followingRedirects().post('/login', { email, password });
res.assertOk(); // landed on dashboard, not the 302

withoutFollowingRedirects()

withoutFollowingRedirects(): this

Defined in: testing/src/TestApp.ts:142

Disable redirect following (restores default behaviour).

Returns

this

withHeaders()

withHeaders(headers): this

Defined in: testing/src/TestApp.ts:154

Merge extra headers into every request sent by this TestApp instance. Useful for setting Accept, Authorization, or custom app headers globally.

Parameters

headers

Record<string, string>

Returns

this

Example

app.withHeaders({ 'X-App-Version': '2' });

asJson()

asJson(): this

Defined in: testing/src/TestApp.ts:168

Send the request as an API client: Accept: application/json. Errors then come back as JSON rather than as the rendered HTML error page, which is what the JSON assertions expect.

Returns

this

Example

const res = await app.asJson().post('/api/posts', { title: '' });
res.assertUnprocessable().assertInvalid('title');

withCookie()

withCookie(name, value): this

Defined in: testing/src/TestApp.ts:178

Attach a cookie to every subsequent request.

Parameters

name

string

value

string

Returns

this

Example

app.withCookie('theme', 'dark');

withCookies()

withCookies(cookies): this

Defined in: testing/src/TestApp.ts:184

Attach several cookies to every subsequent request.

Parameters

cookies

Record<string, string>

Returns

this

withoutCookies()

withoutCookies(): this

Defined in: testing/src/TestApp.ts:190

Drop all cookies added with withCookie/withCookies.

Returns

this

withoutExceptionHandling()

withoutExceptionHandling(): this

Defined in: testing/src/TestApp.ts:211

Stop converting exceptions into error pages: the error is captured and the response is a bare 500, so res.exception() hands you the original and any failing assertion quotes its stack.

Reach for it when a test is failing on a 500 and the rendered page is telling you nothing. Errors are captured either way — this additionally silences the handler's reporting, so an expected failure stops writing a stack trace into the test output.

Returns

this

Example

const res = await app.withoutExceptionHandling().get('/checkout');
expect(res.exception()).toBeInstanceOf(PaymentDeclinedError);

withExceptionHandling()

withExceptionHandling(): this

Defined in: testing/src/TestApp.ts:222

Restore normal exception rendering (the default).

Returns

this

request()

request(url, init?): Promise<TestResponse>

Defined in: testing/src/TestApp.ts:233

Make an HTTP request to the test server. Merges any global headers and the auth cookie automatically.

Parameters

url

string

init?

RequestInit = {}

Returns

Promise<TestResponse>

get()

get(url, headers?): Promise<TestResponse>

Defined in: testing/src/TestApp.ts:282

Send a GET request.

Parameters

url

string

headers?

Record<string, string> = {}

Returns

Promise<TestResponse>

head()

head(url, headers?): Promise<TestResponse>

Defined in: testing/src/TestApp.ts:287

Send a HEAD request.

Parameters

url

string

headers?

Record<string, string> = {}

Returns

Promise<TestResponse>

options()

options(url, headers?): Promise<TestResponse>

Defined in: testing/src/TestApp.ts:292

Send an OPTIONS request.

Parameters

url

string

headers?

Record<string, string> = {}

Returns

Promise<TestResponse>

post()

post(url, body, headers?): Promise<TestResponse>

Defined in: testing/src/TestApp.ts:297

Send a POST request with a JSON body.

Parameters

url

string

body

unknown

headers?

Record<string, string> = {}

Returns

Promise<TestResponse>

put()

put(url, body, headers?): Promise<TestResponse>

Defined in: testing/src/TestApp.ts:310

Send a PUT request with a JSON body.

Parameters

url

string

body

unknown

headers?

Record<string, string> = {}

Returns

Promise<TestResponse>

patch()

patch(url, body, headers?): Promise<TestResponse>

Defined in: testing/src/TestApp.ts:323

Send a PATCH request with a JSON body.

Parameters

url

string

body

unknown

headers?

Record<string, string> = {}

Returns

Promise<TestResponse>

delete()

delete(url, headers?): Promise<TestResponse>

Defined in: testing/src/TestApp.ts:336

Send a DELETE request.

Parameters

url

string

headers?

Record<string, string> = {}

Returns

Promise<TestResponse>

postForm()

postForm(url, body?, headers?): Promise<TestResponse>

Defined in: testing/src/TestApp.ts:354

Submit a URL-encoded form, the way a browser posts one.

A JSON post() does not exercise the same path: form submits are what trigger the redirect-back-with-errors branch of validation, the CSRF check, and any middleware that reads application/x-www-form-urlencoded. A route meant for a browser should be tested the way a browser reaches it.

Parameters

url

string

body?

Record<string, TestFormValue> = {}

headers?

Record<string, string> = {}

Returns

Promise<TestResponse>

Example

const res = await app.postForm('/posts', { title: 'Hello', published: true });
res.assertRedirect('/posts');

putForm()

putForm(url, body?, headers?): Promise<TestResponse>

Defined in: testing/src/TestApp.ts:363

Submit a URL-encoded form with PUT.

Parameters

url

string

body?

Record<string, TestFormValue> = {}

headers?

Record<string, string> = {}

Returns

Promise<TestResponse>

patchForm()

patchForm(url, body?, headers?): Promise<TestResponse>

Defined in: testing/src/TestApp.ts:372

Submit a URL-encoded form with PATCH.

Parameters

url

string

body?

Record<string, TestFormValue> = {}

headers?

Record<string, string> = {}

Returns

Promise<TestResponse>

multipart()

multipart(url, body?, headers?, method?): Promise<TestResponse>

Defined in: testing/src/TestApp.ts:394

Submit a multipart/form-data request — the only way to exercise a route that reads uploaded files.

Pair it with fakeFile to build the attachments; plain values are sent as ordinary fields alongside them.

Parameters

url

string

body?

Record<string, TestFormValue> = {}

headers?

Record<string, string> = {}

method?

"POST" | "PUT" | "PATCH"

Returns

Promise<TestResponse>

Example

const res = await app.multipart('/avatar', {
  name: 'Alice',
  avatar: fakeFile.image('avatar.png', { width: 64, height: 64 }),
});
res.assertCreated();

close()

close(): Promise<void>

Defined in: testing/src/TestApp.ts:419

Stop the test server and shut the app's providers down. Call in afterAll().

Returns

Promise<void>