All of it ships with TypeScript types and zero runtime dependencies.

Who actually uses this

Two groups, and the package works for both:

If you do test automation or QA, you get HTTP checks, polling for eventual consistency, soft assertions so one run reports every problem, snapshots, login chaining, fake data, and a CLI to run whole folders of tests.

If you're a backend or full-stack dev, you write integration tests right next to your unit tests in whatever runner you already use, and you can reuse the expect, the utility belt, and the schema tools in app code too.

One thing to be clear about: two-go is for API and service testing (integration and e2e). It is not a unit test runner. It plugs into the runner you already have. The checks just happen to read like the unit test assertions you're used to.

Table of contents

• Install
• Five minute tour
• The three pieces
• Subpath imports
• Building a request
• HTTP checks
• expect() for any value
• Soft assertions
• Polling slow endpoints
• Snapshots
• Sessions and chaining
• Fake data
• Async helpers
• Utility belt
• Schema validation and inference
• Debugging with curl and logging
• Running tests
• BDD style
• Importing from OpenAPI or Postman
• Generating tests with AI
• TypeScript
• Docker
• Recipes
• two-go next to other tools
• FAQ
• Roadmap
• Contributing
• License

Install

npm install two-go --save-dev

You need Node 18 or newer, because it uses the built-in fetch. It's ESM only, so use import (or a dynamic import() from CommonJS). There are no runtime dependencies.

Five minute tour

import { go } from "two-go";

const api = go("https://api.example.com");

const res = await api
  .get("/users")
  .query({ page: 1 })
  .expectStatus(200)
  .expectJson("data[0].id", 1);

// You still get the response back to poke at.
console.log(res.status, res.time, res.get("data[0].name"));

go() takes a base URL, or an options object if you want default headers and a timeout for every request:

const api = go({
  baseURL: "https://api.example.com",
  headers: { "x-api-key": "secret" },
  timeout: 10000,
});

The three pieces

There isn't much to learn. There's a client, a request builder, and a response.

GoClient comes from go(). It holds the base URL, default headers, and timeout, and it has one method per HTTP verb.

RequestBuilder is what api.get("/x") returns. You chain configuration and checks onto it, then await it. It's a thenable, so awaiting it is what actually sends the request. You can also call .run() if you prefer.

GoResponse is the resolved result. It carries the parsed body and the metadata, plus every check method.

const builder = api.get("/users"); // nothing sent yet
const res = await builder;          // now it's sent, checks ran

A GoResponse gives you:

Subpath imports

Pull everything from two-go, or grab just one area from a subpath. Every subpath ships its own types.

Building a request

Every verb (get, put, post, patch, delete, head, options) returns a builder you can chain.

await api.post("/users")
  .header("x-request-id", "abc")           // one header
  .headers({ "x-trace": "1", lang: "en" }) // several at once
  .query({ page: 1, tags: ["a", "b"] })    // array values repeat the key
  .bearer("TOKEN")                         // authorization: Bearer TOKEN
  .json({ name: "Ada", role: "admin" })    // JSON body and content-type
  .timeout(5000)                           // overrides the client default
  .expectStatus(201);

A few things worth knowing. If you pass an absolute http(s):// URL to a verb, the base URL is ignored. Timeouts use AbortController and reject with a clear message when they fire. Header keys are lowercased so merging behaves the same every time.

HTTP checks

You can queue checks on the builder, where they run in order once you await it, or call them on a resolved response. Either way they return the response so you can keep chaining, and they throw an AssertionError on failure. Messages look like <METHOD> <URL> -> <what went wrong>.

Status:

Headers and cookies:

Body and JSON:

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

res.expectValue("data[0].id").toBeGreaterThan(0);
res.expectValue("data").toHaveLength(2);
res.expectJsonContains("users", { id: 2 });            // subset match
res.expectSorted("data", { key: "id", order: "asc" });

About matchers: expectHeader, expectJson, and expectBody take a flexible matcher. A RegExp is tested against the stringified value. A function is treated as a predicate, so a truthy return passes. An object or array is compared deeply. Anything else is compared with ===.

await api.get("/users")
  .expectJson("data[0].role", (role) => role === "admin")
  .expectJson("meta", { page: 1, total: 2 })
  .expectHeader("x-trace-id", /^[0-9a-f-]+$/);

expect() for any value

expect(value) is not tied to responses, you can use it on anything. It has .not for negation and .resolves / .rejects for promises.

import { expect } from "two-go";

expect(2 + 2).toBe(4);
expect({ a: 1, b: 2 }).toMatchObject({ a: 1 }