gateproof

E2E testing harness. Observe logs, run actions, assert results.

Minimal surface area. Maximum power.

Quick Start

import { Gate, Act, Assert } from "gateproof";
import { CloudflareProvider } from "gateproof/cloudflare";

const provider = CloudflareProvider({
  accountId: process.env.CLOUDFLARE_ACCOUNT_ID!,
  apiToken: process.env.CLOUDFLARE_API_TOKEN!
});

const result = await Gate.run({
  observe: provider.observe({ backend: "analytics", dataset: "worker_logs" }),
  act: [Act.browser({ url: "https://my-worker.workers.dev" })],
  assert: [Assert.noErrors(), Assert.hasAction("request_received")]
});

if (result.status !== "success") process.exit(1);

That's it. Three concepts: Gate, Act, Assert.

Core API

Gate.run(spec)

Run a gate. Returns a result with status, logs, and evidence.

Actions

Act.exec("command")              // Run shell command
Act.browser({ url, headless? })  // Browser automation (needs playwright)
Act.wait(ms)                     // Sleep
Act.deploy({ worker })           // Deploy marker

Assertions

Assert.noErrors()                // No error logs
Assert.hasAction("name")         // Action was logged
Assert.hasStage("worker")        // Stage was seen
Assert.custom("name", fn)        // Custom: (logs) => boolean

Result

{
  status: "success" | "failed" | "timeout",
  durationMs: number,
  logs: Log[],
  evidence: {
    requestIds: string[],
    stagesSeen: string[],
    actionsSeen: string[],
    errorTags: string[]
  },
  error?: Error
}

Plug Your Backend

gateproof works with any observability backend. Just implement the Backend interface:

interface Backend {
  start(): Effect.Effect<LogStream, ObservabilityError>;
  stop(): Effect.Effect<void, ObservabilityError>;
}

See patterns/ for examples including:

Cloudflare Analytics Engine
Cloudflare Workers Logs API
CLI Stream (local dev)
Custom backends

Cloudflare Backends

const provider = CloudflareProvider({ accountId, apiToken });

// Analytics Engine (recommended)
provider.observe({ backend: "analytics", dataset: "worker_logs" })

// Workers Logs API
provider.observe({ backend: "workers-logs", workerName: "my-worker" })

// CLI Stream (local dev)
provider.observe({ backend: "cli-stream", workerName: "my-worker" })

Examples

See patterns/ for complete examples:

patterns/basic/ - Basic usage patterns
patterns/cloudflare/ - Cloudflare-specific patterns
patterns/ci-cd/ - CI/CD integration
patterns/advanced/ - Advanced patterns

CI/CD

gateproof works great in CI/CD. See patterns/ci-cd/github-actions.ts for examples.

Requirements

Node.js 18+ or Bun
playwright (optional, for Act.browser)
Cloudflare credentials (for CloudflareProvider, or bring your own backend)

License

MIT