Advanced Topics

import { StandardSchemaV1 } from "@standard-schema/spec";
import type { Runner } from "runners";

// Using a custom validator
const CustomInputSchema: StandardSchemaV1<string, string> = {
  "~standard": {
    validate: (value) => {
      if (typeof value !== "string") {
        return { issues: [{ message: "Must be string" }] };
      }
      return { value };
    },
  },
};

export const customRunner: Runner<typeof CustomInputSchema> = async (
  ctx,
  input
) => {
  "use runner";
  // input is typed as string
  return { name: "custom", status: "pass" };
};

# Build extracts schemas automatically
npm run build

const runRequest = {
  runners: [/* ... */],
  mode: "remote",
  concurrency: 10, // Run 10 jobs in parallel
};

// Multiple runners can share browser context
const { page } = await withPlaywright(ctx, url);
// Browser is reused for subsequent runners

// Runners loaded on-demand
const runner = await import(`./runners/${runnerName}`);

async function runWithRetry(
  runner: Runner,
  context: RunnerContext,
  input: unknown,
  maxRetries = 3
) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await runner(context, input);
    } catch (error) {
      if (attempt === maxRetries) {
        throw error;
      }
      
      // Exponential backoff
      await new Promise(resolve =>
        setTimeout(resolve, Math.pow(2, attempt) * 1000)
      );
    }
  }
}

import { describe, it, expect } from "vitest";
import { cookieBannerTest } from "./runners";

describe("cookieBannerTest", () => {
  it("should pass when banner is visible", async () => {
    const context = {
      log: () => {},
      region: "us-east-1",
    };
    
    const result = await cookieBannerTest(context, {
      url: "https://example.com",
    });
    
    expect(result.status).toBe("pass");
  });
});

import { runRunners } from "runners";
import { cookieBannerTest } from "./runners";

describe("Runner Integration", () => {
  it("should execute runners", async () => {
    const result = await runRunners({
      runners: [cookieBannerTest],
      region: "us-east-1",
    });
    
    expect(result.results).toHaveLength(1);
    expect(result.results[0].status).toBe("pass");
  });
});

import { withPlaywright } from "runners/playwright";

export const customBrowserRunner: Runner = async (ctx, input) => {
  "use runner";
  
  const { browser } = await withPlaywright(ctx, input.url);
  
  // Access browser directly
  const context = await browser.newContext({
    viewport: { width: 1920, height: 1080 },
    userAgent: "Custom User Agent",
  });
  
  const page = await context.newPage();
  // ... use custom page
};

export const multiPageRunner: Runner = async (ctx, input) => {
  "use runner";
  
  const { browser } = await withPlaywright(ctx, input.url);
  
  const pages = await Promise.all([
    browser.newPage(),
    browser.newPage(),
    browser.newPage(),
  ]);
  
  // Use multiple pages
  await Promise.all(pages.map(page => page.goto(input.url)));
  
  // ... rest of logic
};