@cogniqa-app/recorder

Local browser recorder for CogniQA — launches a real browser on your own machine so you can record test steps by simply clicking through your application. No browser ever runs on CogniQA's servers during recording.

Table of Contents

• What is this?
• Features
• Prerequisites
• Installation
• Usage
  • Start the recorder
  • Disable autostart
• Configuration
  • Changing the local port
  • Self-hosted / development setups
• How It Works
• Security
• System Requirements
• Troubleshooting
• License

What is this?

@cogniqa-app/recorder is a companion CLI for CogniQA users. When you click "Record" inside the CogniQA web app, this locally-running service:

1. Receives a secure, one-time ticket from CogniQA
2. Launches a real Chromium browser window on your machine
3. Replays any existing precondition steps so you start from the right page
4. Captures every click, fill, and navigation as a structured test step
5. Streams those steps back to CogniQA in real time

Because the browser runs locally, you can interact with internal sites, VPN-protected apps, or anything behind your corporate firewall — none of your application traffic leaves your machine.

Features

• Local-first recording — Browser runs on your machine, not in the cloud
• Warm-start replay — Automatically replays existing login/precondition steps before recording starts
• Playwright-powered — Built on the same recording engine as npx playwright codegen
• Electron overlay — Clean floating toolbar for Run / Done / Delete controls
• Auto-launch — Optionally registers itself to start automatically when you log in
• Single-session safety — Only one recording session at a time; accidental double-starts are rejected
• Origin-locked — Only accepts commands from the CogniQA web origin

Prerequisites

• Node.js >= 18.0.0 (LTS recommended)
• npm or npx (comes with Node.js)

The recording window runs on Electron, which is downloaded automatically during install — no separate browser install is needed.

Installation

You do not need to clone this repository. Install directly from npm:

npm install -g @cogniqa-app/recorder

Or run on-demand without installing:

npx @cogniqa-app/recorder listen

After global installation, the binary is available as:

cogniqa-recorder listen

Usage

Start the recorder

Leave this running in a terminal while you use CogniQA:

cogniqa-recorder listen

You will see:

[recorder] Listening on http://127.0.0.1:51820 — leave this running, then click
[recorder] "Record" in CogniQA. Press Ctrl+C to stop.

On the very first successful run, the recorder will also register itself to start automatically at login (you can disable this later).

Disable autostart

If you no longer want the recorder to start automatically when you log in:

cogniqa-recorder disable

Configuration

No configuration is required for normal use with the hosted CogniQA instance.

Changing the local port

If the default port is already taken, you can override it:

# macOS / Linux
COGNIQA_RECORDER_PORT=51900 cogniqa-recorder listen

# Windows (PowerShell)
$env:COGNIQA_RECORDER_PORT=51900; cogniqa-recorder listen

The recorder only ever binds to 127.0.0.1 (localhost). It is never reachable from another machine on your network, regardless of which port it uses.

Self-hosted / development setups

By default the recorder talks to the hosted CogniQA for its release channel: latest builds accept only https://cogniqa.fissionlabs.com, and @beta / @stage builds accept only https://dev-cogniqa.fissionlabs.com.

If you are running your own CogniQA backend and web app locally, set these before starting the recorder:

# macOS / Linux
COGNIQA_API_URL=http://localhost:3001 COGNIQA_WEB_ORIGIN=http://localhost:3000 cogniqa-recorder listen

# Windows (PowerShell)
$env:COGNIQA_API_URL="http://localhost:3001"; $env:COGNIQA_WEB_ORIGIN="http://localhost:3000"; cogniqa-recorder listen

How It Works

┌─────────────────┐         ┌──────────────────────────┐         ┌─────────────────┐
│  CogniQA Web    │ ──────► │  @cogniqa-app/recorder   │ ──────► │  Chromium       │
│  (your browser) │  ticket │  (localhost :51820)      │  CDP    │  (your machine) │
└─────────────────┘         └──────────────────────────┘         └─────────────────┘
                                   │                                    │
                                   │  Playwright recorder API           │
                                   │  (clicks, fills, navigations)      │
                                   │                                    │
                                   ▼                                    ▼
                         ┌──────────────────────────┐         ┌─────────────────┐
                         │  Electron overlay window │         │  CogniQA API    │
                         │  (Run / Done / Delete)   │         │  (step stream)  │
                         └──────────────────────────┘         └─────────────────┘

1. Ticket handshake — When you click "Record" in CogniQA, the web app generates a single-use ticket and POSTs it to the local recorder's /start endpoint.
2. Validation — The recorder immediately redeems the ticket with the CogniQA API. Invalid, expired, or already-used tickets are rejected.
3. Browser launch — A headed Chromium window opens via Playwright. Any existing precondition steps are replayed first so you land on the correct page.
4. Recording — Playwright's internal recorder engine captures every actionable event.
5. Real-time sync — Each captured step is sent back to the CogniQA web tab via polling on /status.
6. Finish — Click Done in the floating Electron toolbar (or close the browser window) to end the session.

Security

• Origin validation — Every incoming request is checked against the allowed-origin list. Cross-origin requests are rejected before they reach any handler.
• One-time tickets — Recording sessions can only be initiated with a cryptographically random, single-use ticket minted by the CogniQA backend.
• Local-only binding — The HTTP server binds exclusively to 127.0.0.1; it never accepts connections from other devices on your network.
• No persistent credentials — The recorder does not store API keys, passwords, or session tokens. The only network call it ever makes is ticket redemption.
• Private Network Access — CORS headers include Access-Control-Allow-Private-Network so modern Chrome versions allow the hosted CogniQA app to reach your localhost recorder.

System Requirements

A local graphical display is required because the recorder launches a headed browser window. It will not work in a headless SSH session without X11 forwarding.

Troubleshooting

"Could not register to start automatically at login"

Corporate-managed machines may block login-item registration. This is a non-fatal warning — just run cogniqa-recorder listen again after reboot.

"Port 51820 is already in use"

The recorder automatically tries ports 51820 through 51825. If all are taken, set a different base port:

COGNIQA_RECORDER_PORT=51900 cogniqa-recorder listen

Browser does not open

If the Electron window can't start (e.g. the Electron binary wasn't downloaded because install ran with --ignore-scripts or behind a proxy), the recorder falls back to a standalone Chromium window. That fallback needs Playwright's Chromium:

npx playwright install chromium

"Ticket is invalid, expired, or already used"

Tickets are single-use and time-bounded. Refresh the CogniQA page and click Record again to get a fresh ticket.

Origin mismatch errors

If you are self-hosting CogniQA, see the Self-hosted / development setups section above to point the recorder at your local web origin.

License

UNLICENSED — see package.json for details.

Repository: github.com/flabdev/CogniQA
Issues: github.com/flabdev/CogniQA/issues
Homepage: github.com/flabdev/CogniQA/tree/main/apps/recorder-cli#readme