Skip to main content

​
Overview

Vulcn v0.3.0 introduces a driver-based architecture that makes the recording and replay system modular and extensible. Instead of being limited to web applications, Vulcn can now support multiple recording targets through drivers.

​
What is a Driver?

A driver is a package that provides:
  1. RecorderDriver - Captures interactions for a specific target type
  2. RunnerDriver - Replays sessions with payload injection
  3. Auto-Crawl (optional) - Automatically discovers forms and injection points
Each driver defines its own step types. For example, the browser driver defines:
  • browser.navigate - Navigate to a URL
  • browser.click - Click an element
  • browser.input - Type into a form field
  • browser.keypress - Press a key

​
Available Drivers

Browser

Web application testing with Playwright

API

HTTP/REST API testing (coming soon)

CLI

Command-line tool testing (coming soon)

​
Session Format

Sessions now include a driver field to indicate which driver recorded them: 
name: Login Test
driver: browser
driverConfig:
  browser: chromium
  startUrl: https://example.com/login
  viewport:
    width: 1280
    height: 720
steps:
  - id: step_001
    type: browser.navigate
    url: https://example.com/login
    timestamp: 0
  - id: step_002
    type: browser.input
    selector: input[name="username"]
    value: testuser
    injectable: true
    timestamp: 1500
metadata:
  recordedAt: "2026-02-06T12:00:00Z"
Step types are namespaced (browser.input instead of just input) to avoid conflicts between drivers.

​
Driver API

Drivers implement two interfaces:

​
RecorderDriver

interface RecorderDriver {
  start(
    config: Record<string, unknown>,
    options: RecordOptions,
  ): Promise<RecordingHandle>;

  // Optional: auto-discover forms and generate sessions
  crawl?(
    config: Record<string, unknown>,
    options: CrawlOptions,
  ): Promise<Session[]>;
}

interface RecordingHandle {
  stop(): Promise<Session>;
  abort(): Promise<void>;
  getSteps(): Step[];
  addStep(step: Omit<Step, "id" | "timestamp">): void;
}
The crawl() method is optional. Only drivers that support automated form discovery need to implement it. Currently, only the browser driver supports auto-crawl.

​
RunnerDriver

interface RunnerDriver {
  execute(session: Session, ctx: RunContext): Promise<RunResult>;
}

​
Using Drivers

​
With CLI

# Record with browser driver (default)
vulcn record https://example.com

# Specify driver explicitly
vulcn record https://example.com --driver browser

# Auto-crawl: discover forms automatically (no manual recording)
vulcn record https://example.com --auto

​
Programmatically

import { DriverManager, driverManager } from "@vulcn/engine";
import browserDriver from "@vulcn/driver-browser";

// Register driver
driverManager.register(browserDriver);

// Option 1: Manual recording
const handle = await driverManager.startRecording("browser", {
  startUrl: "https://example.com",
  browser: "chromium",
});

// ... user interacts ...
const session = await handle.stop();

// Option 2: Auto-crawl (discovers forms automatically)
const sessions = await driverManager.crawl(
  "browser",
  {
    startUrl: "https://example.com",
    browser: "chromium",
    headless: true,
  },
  {
    maxDepth: 2,
    maxPages: 20,
  },
);

​
Creating Custom Drivers

See Creating Drivers for a complete guide on building your own driver.

Browser Driver

Learn about the browser driver and its configuration options