Skip to main content
zerotal

Documentation

Documentation / zerotal / testing / TestResponse

Class: TestResponse

Defined in: packages/testing/src/TestResponse.ts:44

Constructors

Constructor

new TestResponse(_res, _body, context?): TestResponse

Defined in: packages/testing/src/TestResponse.ts:53

Parameters

_res

Response

_body

string

context?

TestResponseContext & object = {}

Returns

TestResponse

Accessors

status

Get Signature

get status(): number

Defined in: packages/testing/src/TestResponse.ts:92

Returns

number

ok

Get Signature

get ok(): boolean

Defined in: packages/testing/src/TestResponse.ts:95

Returns

boolean

headers

Get Signature

get headers(): Headers

Defined in: packages/testing/src/TestResponse.ts:98

Returns

Headers

Methods

of()

static of(res, context?): Promise<TestResponse>

Defined in: packages/testing/src/TestResponse.ts:65

Read a Response's body (and session) and wrap it. The only async step in the class.

Parameters

res

Response

context?

TestResponseContext = {}

Returns

Promise<TestResponse>

exception()

exception(): unknown

Defined in: packages/testing/src/TestResponse.ts:111

The exception the request raised, when the suite called TestApp.withoutExceptionHandling. undefined otherwise, and when the request completed without throwing.

Returns

unknown

Example

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

assertStatus()

assertStatus(expected): this

Defined in: packages/testing/src/TestResponse.ts:118

Assert the HTTP status code. Chainable.

Parameters

expected

number

Returns

this

assertOk()

assertOk(): this

Defined in: packages/testing/src/TestResponse.ts:128

Assert HTTP 200 OK.

Returns

this

assertCreated()

assertCreated(): this

Defined in: packages/testing/src/TestResponse.ts:133

Assert HTTP 201 Created.

Returns

this

assertNoContent()

assertNoContent(): this

Defined in: packages/testing/src/TestResponse.ts:138

Assert HTTP 204 No Content.

Returns

this

assertMovedPermanently()

assertMovedPermanently(): this

Defined in: packages/testing/src/TestResponse.ts:143

Assert HTTP 301 Moved Permanently.

Returns

this

assertUnauthorized()

assertUnauthorized(): this

Defined in: packages/testing/src/TestResponse.ts:148

Assert HTTP 401 Unauthorized.

Returns

this

assertForbidden()

assertForbidden(): this

Defined in: packages/testing/src/TestResponse.ts:153

Assert HTTP 403 Forbidden.

Returns

this

assertNotFound()

assertNotFound(): this

Defined in: packages/testing/src/TestResponse.ts:158

Assert HTTP 404 Not Found.

Returns

this

assertUnprocessable()

assertUnprocessable(): this

Defined in: packages/testing/src/TestResponse.ts:163

Assert HTTP 422 Unprocessable Entity.

Returns

this

assertServerError()

assertServerError(): this

Defined in: packages/testing/src/TestResponse.ts:168

Assert HTTP 500 Internal Server Error.

Returns

this

assertSuccessful()

assertSuccessful(): this

Defined in: packages/testing/src/TestResponse.ts:173

Assert the status is in the 2xx range.

Returns

this

assertRedirect()

assertRedirect(url): this

Defined in: packages/testing/src/TestResponse.ts:183

Assert the response is a redirect to url.

Parameters

url

string

Returns

this

assertHeader()

assertHeader(name, value?): this

Defined in: packages/testing/src/TestResponse.ts:207

Assert a response header is present and optionally matches a value.

Parameters

name

string

value?

string

Returns

this

Example

res.assertHeader('Content-Type');
res.assertHeader('Content-Type', 'application/json');

assertHeaderMissing()

assertHeaderMissing(name): this

Defined in: packages/testing/src/TestResponse.ts:225

Assert a response header is absent.

Parameters

name

string

Returns

this

assertJson()

assertJson(expected): this

Defined in: packages/testing/src/TestResponse.ts:240

Parse the body as JSON and assert that every key in expected matches. Extra keys in the actual response are allowed.

Parameters

expected

Record<string, unknown>

Returns

this

assertJsonPath()

assertJsonPath(path, expected): this

Defined in: packages/testing/src/TestResponse.ts:264

Assert a value at a dot-notation path in the JSON body.

Parameters

path

string

expected

unknown

Returns

this

Example

res.assertJsonPath('user.name', 'Alice');
res.assertJsonPath('data.0.id', 1);

assertJsonCount()

assertJsonCount(count, key?): this

Defined in: packages/testing/src/TestResponse.ts:286

Assert the JSON body (or a key within it) is an array of the given length.

Parameters

count

number

key?

string

Returns

this

Example

res.assertJsonCount(3);          // top-level array
res.assertJsonCount(3, 'data');  // array at body.data

assertSee()

assertSee(needle): this

Defined in: packages/testing/src/TestResponse.ts:316

Assert the response body contains the given string.

Parameters

needle

string

Returns

this

Example

res.assertSee('Welcome, Alice');

assertDontSee()

assertDontSee(needle): this

Defined in: packages/testing/src/TestResponse.ts:329

Assert the response body does NOT contain the given string.

Parameters

needle

string

Returns

this

Example

res.assertDontSee('Error');

assertBodyContains()

assertBodyContains(needle): this

Defined in: packages/testing/src/TestResponse.ts:339

Assert the response body contains the given string. Alias of assertSee.

Parameters

needle

string

Returns

this

assertSeeText()

assertSeeText(needle): this

Defined in: packages/testing/src/TestResponse.ts:352

Assert the body contains needle once tags are stripped — the text a user would actually read. Use it when markup sits between the words you expect, which is what makes a plain assertSee on rendered HTML brittle.

Parameters

needle

string

Returns

this

Example

// Passes against `<strong>Welcome</strong>, <em>Alice</em>`
res.assertSeeText('Welcome, Alice');

assertDontSeeText()

assertDontSeeText(needle): this

Defined in: packages/testing/src/TestResponse.ts:361

Assert the tag-stripped body does NOT contain needle.

Parameters

needle

string

Returns

this

json()

json<T>(): T

Defined in: packages/testing/src/TestResponse.ts:374

Parse and return the full JSON body.

Type Parameters

T

T = unknown

Returns

T

text()

text(): string

Defined in: packages/testing/src/TestResponse.ts:379

Return the full response body as text.

Returns

string

validationErrors()

validationErrors(): Record<string, string[]> | null

Defined in: packages/testing/src/TestResponse.ts:394

The validation errors this response carries, from whichever place the response put them: a JSON API gets 422 { errors: {...} }, while a form submit gets a redirect with the errors flashed to the session. Returns null when the response carries none.

Returns

Record<string, string[]> | null

Example

const errors = res.validationErrors();

assertInvalid()

assertInvalid(fields?): this

Defined in: packages/testing/src/TestResponse.ts:421

Assert the request failed validation, optionally naming the fields.

Covers both shapes a failed validation takes: the 422 JSON body an API client receives, and the errors a form submit flashes to the session before redirecting back. You assert the same way for either.

Parameters

fields?

string | string[] | Record<string, string>

Returns

this

Example

res.assertInvalid();                      // failed on something
res.assertInvalid('email');               // failed on email
res.assertInvalid(['email', 'password']); // failed on both
res.assertInvalid({ email: 'required' }); // and the message contains "required"

assertValid()

assertValid(fields?): this

Defined in: packages/testing/src/TestResponse.ts:470

Assert the response carries no validation errors — for the named fields when given, or for any field at all when called bare.

Parameters

fields?

string | string[]

Returns

this

Example

res.assertValid();        // nothing failed
res.assertValid('email'); // email in particular did not fail

assertCookie()

assertCookie(name, value?): this

Defined in: packages/testing/src/TestResponse.ts:510

Assert that the response sets a cookie with the given name. Optionally assert its value.

Parameters

name

string

value?

string

Returns

this

Example

res.assertCookie('zerotal_session');
res.assertCookie('theme', 'dark');

assertCookieMissing()

assertCookieMissing(name): this

Defined in: packages/testing/src/TestResponse.ts:535

Assert that the response does NOT set a cookie with the given name.

Parameters

name

string

Returns

this

Example

res.assertCookieMissing('remember_me');

session()

session(): Record<string, unknown> | null

Defined in: packages/testing/src/TestResponse.ts:557

The session the response carries, decoded through the app's own session driver. null when the response set no session cookie.

Returns

Record<string, unknown> | null

Throws

When the response was not produced by a TestApp with a resolvable session.driver — there is nothing to decode with.

Example

expect(res.session()?.['cart_id']).toBe(7);

assertSessionHas()

assertSessionHas(key, value?): this

Defined in: packages/testing/src/TestResponse.ts:569

Assert that the session contains the given key (optionally matching value).

Parameters

key

string

value?

unknown

Returns

this

Example

res.assertSessionHas('status', 'saved');
res.assertSessionHas('user_id');

assertSessionMissing()

assertSessionMissing(key): this

Defined in: packages/testing/src/TestResponse.ts:607

Assert that the session does NOT contain the given key.

A session that cannot be decoded throws rather than passing: "I could not read the session" is not evidence that the key is absent, and treating it as such is an assertion that can never fail.

Parameters

key

string

Returns

this

Example

res.assertSessionMissing('errors');

assertSessionHasErrors()

assertSessionHasErrors(fields?): this

Defined in: packages/testing/src/TestResponse.ts:628

Assert the session carries flashed validation errors, optionally for the named fields. The form-submit counterpart of assertInvalid.

Parameters

fields?

string | string[]

Returns

this

Example

res.assertSessionHasErrors(['email']);

assertSessionHasNoErrors()

assertSessionHasNoErrors(): this

Defined in: packages/testing/src/TestResponse.ts:635

Assert the session carries no flashed validation errors.

Returns

this

assertAuthenticated()

assertAuthenticated(): this

Defined in: packages/testing/src/TestResponse.ts:649

Assert the response leaves someone signed in — the session carries the user_id that AuthSessionMiddleware hydrates ctx.user from.

Returns

this

Example

const res = await app.followingRedirects().post('/login', creds);
res.assertAuthenticated();

assertAuthenticatedAs()

assertAuthenticatedAs(user): this

Defined in: packages/testing/src/TestResponse.ts:674

Assert the response leaves the given user signed in.

Accepts the user or a bare id, and compares loosely across the number/string divide — a session round-trips through JSON, so an integer key can come back either way depending on the driver.

Parameters

user

string | number | { id: string | number; }

Returns

this

Example

res.assertAuthenticatedAs(user);
res.assertAuthenticatedAs(42);

assertGuest()

assertGuest(): this

Defined in: packages/testing/src/TestResponse.ts:690

Assert the response leaves nobody signed in.

Returns

this

inertia()

inertia(): InertiaPage | null

Defined in: packages/testing/src/TestResponse.ts:712

The Inertia page object this response carries, from either shape the protocol uses: the JSON body of an X-Inertia visit, or the <script data-page> payload embedded in a full page load. null when the response is not an Inertia response.

Returns

InertiaPage | null

assertInertia()

assertInertia(component?, props?): this

Defined in: packages/testing/src/TestResponse.ts:740

Assert the response rendered an Inertia page — optionally the named component, optionally carrying the given props.

Props are matched partially, so you assert the ones the test is about and ignore the shared props riding along with every page.

Parameters

component?

string

props?

Record<string, unknown>

Returns

this

Example

res.assertInertia('Posts/Index');
res.assertInertia('Posts/Show', { post: { id: 1, title: 'Hello' } });

assertInertiaProp()

assertInertiaProp(key, value?): this

Defined in: packages/testing/src/TestResponse.ts:774

Assert the Inertia page carries the named prop, optionally matching a value.

Parameters

key

string

value?

unknown

Returns

this