1. Quickstart: Record in 60 Seconds

Workflow Recorder lets you turn any manual browser task into clean, automated Playwright, Puppeteer, or Selenium scripts without writing code by hand.

Prerequisite: Google Chrome, Microsoft Edge, Brave, or Chromium browser (version 114+).

Step 1: Open Target Page

Navigate to any website or web application you want to automate (e.g. https://app.example.com/login).

Step 2: Launch Recorder

Click the Workflow Recorder extension icon in your Chrome toolbar, or press Ctrl+Shift+R (Cmd+Shift+R on macOS). The floating recorder HUD will appear in the bottom-right corner.

Step 3: Perform User Actions

Click buttons, enter credentials, submit forms, or switch tabs. The HUD automatically tracks your steps, counts events, and inspects each DOM target with real-time stability scoring.

Step 4: Stop & Export

Click Stop Recording on the floating controller. Your complete workflow opens in the 3-panel Workflow Editor, where you can inspect selectors, bind dynamic variables, and export to Playwright TypeScript, Puppeteer, or Selenium Python with 1 click.

2. Installation & Setup

Workflow Recorder offers two installation methods: 1-click install from the Google Chrome Web Store, or building locally from source code.

Method A: Chrome Web Store (Recommended)

Visit the Chrome Web Store.
Click Add to Chrome.
Confirm the extension permissions. The extension icon will appear in your extensions menu.

Method B: Build from Source (Developer Mode)

If you want to contribute, customize features, or run in strictly air-gapped enterprise environments, build from source using Node.js:

# 1. Clone repository
git clone https://github.com/workflow-recorder/workflow-recorder.git
cd workflow-recorder

# 2. Install dependencies & compile Manifest V3 build
npm install
npm run build

# 3. Load unpacked directory in Chrome
• Navigate to chrome://extensions
• Enable "Developer mode" (toggle top right)
• Click "Load unpacked" and select the generated dist/ directory

Offline Security: The compiled build runs 100% locally. No external telemetry calls, tracking pixels, or remote code evaluation.

3. Floating In-Page Recording HUD

While recording is active, a floating control widget renders at the corner of your viewport. It is injected into a closed Shadow DOM (<workflow-recorder-controller>) so it never interferes with page stylesheets or layout.

HUD Control	Action	Keyboard Shortcut
Record / Pause	Temporarily suspends event capture so you can perform setup steps without recording them.	`Alt + P`
Stop & Open Editor	Flushes pending keystrokes, stops capture, and launches the full Workflow Editor.	`Ctrl + Shift + S`
Add Checkpoint Assertion	Enters element inspection mode to click an element and record a text or visibility assertion.	`Alt + A`
Step Counter & Timer	Displays live elapsed time and total recorded steps with real-time selector scores.	—

Non-Interference Guarantee: All elements of the floating controller contain data-workflow-recorder-ignore="true". The recording content script detects this attribute and discards recorder-originated clicks immediately.

4. Action Types & Event Catalog

The recording engine normalizes noisy browser DOM streams into 12 discrete, strongly-typed automation actions:

Action Type	Captured Properties	Description
`navigate`	`url, sanitizedUrl`	Records top-level page navigations, hash changes, and pushState route transitions.
`click`	`target, selector, score, button`	Left, middle, or right click on buttons, links, or interactive elements.
`dblclick`	`target, selector, score`	Rapid double-click actions (deduplicated within 200ms).
`input`	`selector, value, sensitive`	Debounced atomic text fill. Automatically masks passwords as `{{password}}`.
`select`	`selector, value, label`	Selection of an option in a standard `<select>` HTML dropdown.
`checkbox / radio`	`selector, checked`	Toggling checkbox or radio button inputs with explicit boolean state verification.
`scroll`	`position: { x, y }`	Debounced scroll position capture. Triggers after 400ms stabilization.
`hover`	`selector, durationMs`	Recorded when the cursor rests over an element longer than 500ms.
`newTab / closeTab`	`logicalTabId, url`	Lifecycle operations for multi-tab test execution across logical tab keys.
`assertText`	`selector, expectedText, matchType`	Verifies that target element contains or strictly equals the expected text.
`assertVisible`	`selector, state`	Asserts that an element is visible, hidden, or attached to the DOM.

5. The 3-Panel Workflow Editor

After stopping a recording, your workflow opens in the developer-grade 3-panel editor:

Panel 1: Step Hierarchy

Reorder steps via drag-and-drop, toggle steps active or disabled, delete mis-clicks, and add custom sleep intervals or assertion checkpoints.

Panel 2: Step Inspector

Inspect ranked selector candidates, override locators manually, adjust step timeouts (default: 30,000ms), and configure retry backoff limits.

Panel 3: Code & Variables

Real-time syntax-highlighted code output across Playwright, Puppeteer, Selenium, and Cypress. Manage parameterized variables and export scripts.

6. Dynamic Variables & Parameterization

Hardcoded test data leads to fragile test suites. Workflow Recorder allows you to parameterize inputs with mustache or template literals: ${variable_name} or {{variable_name}}.

Defining Variables

In the editor's Variables Tab, create named variables with default values:

{
  "username": "tester@enterprise.io",
  "environment_url": "https://staging.app.io",
  "search_term": "Mechanical Keyboard"
}

In your test steps, replace literal inputs with ${username}. When exported to Playwright TypeScript, the exporter generates a strongly-typed TypeScript interface automatically:

interface WorkflowVariables {
  username: string;
  environment_url: string;
  search_term: string;
}

7. Assertions & Verifications

A workflow without assertions is merely an interaction script. Workflow Recorder provides multiple built-in verification types:

Text Assertion: Verifies that an element contains expected text (e.g. Registration Complete).
Visibility Assertion: Checks that a modal, toast notice, or error alert is visible or detached.
URL Validation: Asserts that the browser URL matches an exact string or regular expression pattern.
Visual Snapshot Checkpoint: Captures a full-page or element screenshot stored locally in IndexedDB.

8. CI/CD Integration & Automated Execution

Scripts exported by Workflow Recorder are 100% standard Playwright, Puppeteer, or Selenium scripts. They execute without any proprietary dependencies or runner wrappers.

Sample GitHub Actions Workflow

Save the following as .github/workflows/e2e.yml in your repository:

name: End-to-End Test Suite
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npx playwright test

9. Troubleshooting & Frequently Asked Questions

Why did my recording miss a dynamic single-page route change?

Modern SPAs (Next.js, Remix, React Router) use HTML5 history.pushState(). Ensure the active tab remains focused so the content script listener can observe the URL mutation.

How do I handle cross-domain iframes?

By default, Chrome MV3 content scripts execute in all frames where matching host permissions apply. When recording inside an iframe, Workflow Recorder binds a frameLocator() chain to the parent window context.

Where is my workflow data stored?

All workflow definitions, step timelines, and screenshot blobs are stored in your browser's local IndexedDB under the database name workflow_recorder_db. No data is ever transmitted to remote cloud servers.

Workflow Recorder Documentation