Mocking & Unit Test

This example demonstrates how to write unit tests for Zuplo handlers by mocking ZuploRequest and ZuploContext. The sample uses Mocha and Sinon for testing and mocking, but the concepts apply to any test framework.

Prerequisites

A Zuplo account. You can sign up for free.
Node.js installed locally for running tests

Working with this Example

Locally

Working locally is the best way to explore and understand the code for this example. You can get a local version by using the Zuplo CLI:

bash

npx create-zuplo-api@latest --example test-mocks

Then, in the project directory run the following commands:

bash

npm install
npm run dev

Running the Tests

To run the unit tests:

bash

npm run unit

Deploy this example to Zuplo

It is also possible to deploy this example directly to your Zuplo account and work with it via the Zuplo Portal. You can do this by clicking the Deploy to Zuplo button anywhere on this page.

How It Works

Mocking ZuploRequest

ZuploRequest can be constructed directly — import it from @zuplo/runtime and pass params (and any other request init options) straight to the constructor. There’s no need to hand-roll a subclass:

typescript

import { ZuploRequest } from "@zuplo/runtime";

const mockRequest = new ZuploRequest("https://my-api.zuplo.app", {
  params: { param1: "hello" },
});

Mocking ZuploContext

Create a mock context object with the properties your handlers use:

typescript

export const context = {
  log: {
    info: () => {},
    warn: () => {},
    error: () => {},
  },
  route: {
    pathPattern: "/test",
  },
  // Add other properties as needed
};

Testing Handlers

With the mocks in place, you can test handlers directly:

typescript

it("Calls the handler and validates the result", async function () {
  const contextSpy = sandbox.spy(context.log, "info");

  const mockRequest = new ZuploRequest("https://test.com", {
    method: 'POST',
    body: JSON.stringify({ hello: "world" })
  });

  const response = await handler1(mockRequest, context);
  const result = await response.json();

  assert(contextSpy.calledOnce);
  assert(result.hello === "world");
});

Mocking External API Calls

Use undici’s MockAgent to mock fetch calls your handlers make. Node’s built-in fetch is its own bundled copy of undici, so setGlobalDispatcher alone won’t reach it — also point globalThis.fetch at undici’s own fetch so the mocked dispatcher is actually used:

typescript

import { MockAgent, setGlobalDispatcher, fetch as undiciFetch } from "undici";

const mockAgent = new MockAgent();
setGlobalDispatcher(mockAgent);
globalThis.fetch = undiciFetch as unknown as typeof globalThis.fetch;

const mockPool = mockAgent.get("https://echo.zuplo.io");
mockPool
  .intercept({ path: "/hello" })
  .reply(200, { data: "mocked response" });

Project Structure

text

├── config/
│   └── routes.oas.json      # Route definitions
├── modules/
│   ├── handler1.ts          # Handler that logs and returns body
│   └── handler2.ts          # Handler that makes external API call
└── unit-tests/
    ├── mocks.ts             # Mock implementations
    └── handlers.spec.ts     # Test file

Test Examples

Testing a Simple Handler

typescript

it("Calls the handler and validates the result", async function () {
  const mockRequest = new ZuploRequest("https://test.com", {
    method: 'POST',
    body: JSON.stringify({ hello: "world" })
  });

  const response = await handler1(mockRequest, context);
  const result = await response.json();

  assert(result.hello === "world");
});

Testing with Path Parameters

typescript

it("Handles path parameters", async function () {
  const mockRequest = new ZuploRequest("https://my-api.zuplo.app", {
    params: { param1: "hello" },
  });

  const result = await handler2(mockRequest, context);
  assert(result.data === "expected value");
});

Using Sinon Spies

typescript

it("Verifies logging was called", async function () {
  const logSpy = sandbox.spy(context.log, "info");

  await handler1(mockRequest, context);

  assert(logSpy.calledOnce);
  assert(logSpy.calledWith({ hello: "world" }));
});

Common Customizations

Add more mock properties: Extend the mock context with request.user, context.custom, etc.
Test policies: Apply the same mocking approach to test custom policies
Test error cases: Verify handlers return appropriate error responses
Integration tests: Use Zuplo’s test framework for end-to-end testing