Expect Helpers

Kyrin provides three assertion helpers for writing clean, readable tests: expect(), expectStatus(), and expectBody().

expect()

A general-purpose assertion utility with a Jest-compatible API.

import { expect } from "kyrin";

toBe(expected)

Strict equality check (===).

expect(2 + 2).toBe(4);
expect("hello").toBe("hello");
expect(true).toBe(true);
expect(null).toBe(null);

toEqual(expected)

Deep equality comparison using JSON.stringify.

expect({ a: 1, b: 2 }).toEqual({ a: 1, b: 2 });
expect([1, 2, 3]).toEqual([1, 2, 3]);

// Objects with different key orders are still equal
expect({ b: 2, a: 1 }).toEqual({ a: 1, b: 2 });

toContain(expected)

Check if a string contains a substring.

expect("Hello, World!").toContain("World");
expect("error: not found").toContain("not found");
expect("success").toContain("suc");

toBeTruthy()

Asserts that the value is truthy (anything that isn't false, 0, "", null, undefined, or NaN).

expect(true).toBeTruthy();
expect(1).toBeTruthy();
expect("hello").toBeTruthy();
expect([]).toBeTruthy();
expect({}).toBeTruthy();

toBeFalsy()

Asserts that the value is falsy.

expect(false).toBeFalsy();
expect(0).toBeFalsy();
expect("").toBeFalsy();
expect(null).toBeFalsy();
expect(undefined).toBeFalsy();

toThrow(error?)

Asserts that a function throws an error. Optionally, check the error message.

// Just check that it throws
expect(() => {
  throw new Error("something went wrong");
}).toThrow();

// Check error message (string match)
expect(() => {
  throw new Error("fail");
}).toThrow("fail");

// Check error message (regex match)
expect(() => {
  throw new Error("validation failed: email is required");
}).toThrow(/email is required/);

// Check error instance
expect(() => {
  throw new Error("oops");
}).toThrow(new Error("oops"));

expectStatus()

A dedicated helper for asserting HTTP response status codes.

import { expectStatus } from "kyrin";

const res = await client.get("/users");
expectStatus(res.status).toBe(200);

// Typical status code checks
expectStatus(res.status).toBe(200);  // OK
expectStatus(res.status).toBe(201);  // Created
expectStatus(res.status).toBe(204);  // No Content
expectStatus(res.status).toBe(301);  // Moved Permanently
expectStatus(res.status).toBe(400);  // Bad Request
expectStatus(res.status).toBe(401);  // Unauthorized
expectStatus(res.status).toBe(403);  // Forbidden
expectStatus(res.status).toBe(404);  // Not Found
expectStatus(res.status).toBe(500);  // Internal Server Error

expectBody()

A dedicated helper for asserting HTTP response bodies.

import { expectBody } from "kyrin";

const res = await client.get("/users");

toEqual(expected)

Deep equality check on the response body.

expectBody(res.body).toEqual({ users: ["Alice", "Bob"] });
expectBody(res.body).toEqual({ id: "123" });

// Works with arrays
expectBody(res.body).toEqual(["a", "b", "c"]);

// Works with nested objects
expectBody(res.body).toEqual({
  data: {
    user: { id: 1, name: "Alice" },
  },
});

toContain(expected)

Check if the stringified response body contains a substring.

expectBody(res.body).toContain("error");
expectBody(res.body).toContain("success");

// Useful for checking error messages
const res = await client.get("/unknown");
expectBody(res.body).toContain("not found");

Complete Example

import { createApp, expect, expectStatus, expectBody } from "kyrin";

describe("Assertion examples", () => {
  let app: ReturnType<typeof createApp>;

  beforeEach(() => {
    app = createApp();
    app.get("/users", () => ({ users: ["Alice", "Bob"] }));
    app.get("/error", () => {
      throw new Error("Something broke");
    });
  });

  test("expect() general assertions", () => {
    expect(1 + 1).toBe(2);
    expect({ a: 1 }).toEqual({ a: 1 });
    expect("hello").toContain("ell");
    expect(true).toBeTruthy();
    expect("").toBeFalsy();
    expect(() => { throw new Error("fail"); }).toThrow();
    expect(() => { throw new Error("fail"); }).toThrow("fail");
  });

  test("expectStatus() for HTTP status codes", async () => {
    const client = app.getClient();
    const res = await client.get("/users");
    expectStatus(res.status).toBe(200);
  });

  test("expectBody() for response bodies", async () => {
    const client = app.getClient();
    const res = await client.get("/users");
    expectBody(res.body).toEqual({ users: ["Alice", "Bob"] });
    expectBody(res.body).toContain("Alice");
  });
});

Next Steps

• Getting Started — TestApp and TestClient
• Mocking Utilities — Spies, stubs, mock database, mock request/response