Skip to content

Testing and runtimes (TypeScript)

Test code that uses the TypeScript SDK with an injected fetch, and what to know about Node, Bun, Deno, Cloudflare Workers and browsers.

The client needs only fetch, so a stub is enough to test it and most runtimes run it unchanged. This page covers the runtime differences and a test with no network.

Runtimes

The client reads three things from outside itself: the global fetch, environment variables (through process.env, or Deno.env when there is no process), and the CLI (through process.getBuiltinModule). Where one of them is missing the client carries on without it.

RuntimeNotes
Node 20 or laterESM and CJS. The CLI token needs 20.16 or later, or 22.3 or later; before that, set SAILFORK_TOKEN or pass token
BunRuns the TypeScript source or the package. The CLI token works
Denoimport Sailfork from 'npm:sailfork'. Environment variables need --allow-env, and without it they read as unset. Pass token explicitly if in doubt
Cloudflare WorkersThere is no environment variable lookup and no CLI. Pass token from a binding, and agent if the Worker acts as an agent
BrowsersNot a supported target. A token in page code is public to every visitor, so keep calls on a server
import Sailfork from 'sailfork';

type Env = { SAILFORK_TOKEN: string };

export default {
	async fetch(_request: Request, env: Env): Promise<Response> {
		const sf = new Sailfork({ token: env.SAILFORK_TOKEN, agent: 'pr-bot' });
		const { items } = await sf.repo('acme/api').pulls.list({ limit: 5 });
		return Response.json(items.map((pull) => ({ number: pull.number, title: pull.title })));
	},
};

Without agent, a Worker's requests carry no agent name, so the organization's agent permissions treat them as a person's. Name the Worker when it should be held to the rules for agents.

Test your code

Inject fetch to run the client against a stub, with no network and no token lookup. Pass token so the client does not try the CLI, maxRetries: 0 so a failure answers at once, and agent: false so the environment of the machine running the test does not change the headers.

import Sailfork, { AgentPolicyError, NotFoundError } from 'sailfork';

type Seen = { url: string; method: string | undefined; headers: Record<string, string>; body: string | undefined };

function stub(answer: (seen: Seen) => Response): { fetch: typeof fetch; calls: Seen[] } {
	const calls: Seen[] = [];
	const fetchStub = (async (input: RequestInfo | URL, init?: RequestInit) => {
		const seen: Seen = {
			url: String(input),
			method: init?.method,
			headers: (init?.headers ?? {}) as Record<string, string>,
			body: typeof init?.body === 'string' ? init.body : undefined,
		};
		calls.push(seen);
		return answer(seen);
	}) as typeof fetch;
	return { fetch: fetchStub, calls };
}

const json = (status: number, body: unknown) =>
	new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });

// A merge a person must approve comes back as a held result.
const held = stub(() => json(202, { held: 'h_1', url: '/requests', message: 'HELD FOR A PERSON: merge acme/api#128' }));
const sf = new Sailfork({ token: 'test', host: 'https://sailfork.test', fetch: held.fetch, maxRetries: 0, agent: false });

const merge = await sf.repo('acme/api').pull(128).merge({ method: 'squash' });
if (merge.status !== 'held') throw new Error('expected a held merge');
if (merge.url !== 'https://sailfork.test/requests') throw new Error(merge.url);
if (held.calls[0]?.url !== 'https://sailfork.test/api/repos/acme/api/pulls/128/merge') throw new Error('wrong route');
if (held.calls[0]?.body !== '{"method":"squash"}') throw new Error('wrong body');
if (held.calls[0]?.headers['idempotency-key'] === undefined) throw new Error('writes send an idempotency key');

// An error answer becomes a typed error.
const missing = stub(() => json(404, { error: 'not found', code: 'not_found' }));
const lost = new Sailfork({ token: 'test', host: 'https://sailfork.test', fetch: missing.fetch, maxRetries: 0, agent: false });
try {
	await lost.repo('acme/api').pull(1).get();
	throw new Error('expected a 404');
} catch (error) {
	if (!(error instanceof NotFoundError)) throw error;
}

const refused = stub(() => json(403, { error: 'declined', code: 'held_declined' }));
const declined = new Sailfork({ token: 'test', host: 'https://sailfork.test', fetch: refused.fetch, maxRetries: 0, agent: false });
await declined.repo('acme/api').pull(1).merge().catch((error: unknown) => {
	if (!(error instanceof AgentPolicyError)) throw error;
});

To test retries, make the stub answer 503 once and then 200. The client sends the same idempotency-key on both attempts, and a test can assert that.

Test a retry

The stub answers 503 once, then 200. The client sends one idempotency-key and reuses it for the second attempt, so a test can assert both the retry and the key.

import Sailfork from 'sailfork';

const keys: (string | undefined)[] = [];
let attempts = 0;
const flaky = (async (_input: RequestInfo | URL, init?: RequestInit) => {
	attempts++;
	keys.push((init?.headers as Record<string, string> | undefined)?.['idempotency-key']);
	return attempts === 1
		? new Response(JSON.stringify({ error: 'busy', code: 'busy' }), { status: 503, headers: { 'content-type': 'application/json' } })
		: new Response(JSON.stringify({ number: 128, state: 'merged' }), { status: 200, headers: { 'content-type': 'application/json' } });
}) as typeof fetch;

const sf = new Sailfork({ token: 'test', host: 'https://sailfork.test', fetch: flaky, agent: false });
const merge = await sf.repo('acme/api').pull(128).merge();

if (attempts !== 2) throw new Error(`expected 2 attempts, got ${attempts}`);
if (keys[0] === undefined || keys[0] !== keys[1]) throw new Error('the key changed between attempts');
if (merge.status !== 'done') throw new Error('expected a done result');

The retry waits 250 to 500 ms before the second attempt, so the test takes about that long. The same topic for Python: Python testing.

Loading Sailfork