Onboarding: checkly/headless-recorder

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/checkly/headless-recorder shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

GO — Healthy across all four use cases

• 8 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 3y ago
• ⚠ Concentrated ownership — top contributor handles 62% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live checkly/headless-recorder repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/checkly/headless-recorder.

What it runs against: a local clone of checkly/headless-recorder — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in checkly/headless-recorder | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 1267 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>checkly/headless-recorder</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of checkly/headless-recorder. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/checkly/headless-recorder.git
#   cd headless-recorder
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of checkly/headless-recorder and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "checkly/headless-recorder(\\.git)?\\b" \\
  && ok "origin remote is checkly/headless-recorder" \\
  || miss "origin remote is not checkly/headless-recorder (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1267 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1237d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/checkly/headless-recorder"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

Headless Recorder is a Chrome extension that records user browser interactions (clicks, typing, navigation) and automatically generates executable Playwright or Puppeteer scripts. It solves the problem of manually writing browser automation code by capturing real user actions and translating them into test scripts, eliminating tedious scripting for testing, scraping, or automation workflows. Single-package Vue 3 + TailwindCSS extension built with vue-cli-plugin-browser-extension. State is managed with Pinia and Vuex (dual setup). Content script in src/ captures browser events; popup/panel UI in Vue components renders the generated script. Tests live in __tests__/ and run via Jest.

Who it's for

QA engineers and developers who write browser automation tests using Playwright/Puppeteer but want to avoid hand-coding selectors and interaction sequences. Also useful for Checkly users who need to generate synthetic monitoring scripts without writing JavaScript by hand.

Maturity & risk

Deprecated as of December 16, 2022 — the project is no longer maintained, receives no bug fixes, and the README explicitly states 'No new changes, support, maintenance or new features are expected.' Despite 3.9K+ Chrome Webstore users, it is a legacy/archived project with no active development.

High risk: project is officially deprecated with zero ongoing maintenance. Dependencies are pinned to 2020–2021 versions (Vue 3.0.6, Playwright 1.10.0, Puppeteer 9.0.0) and will accumulate security vulnerabilities. No recent commits or CI activity visible. Use only if you understand you're inheriting unmaintained code with no upstream support.

Active areas of work

Nothing — the project is archived. The last activity was the deprecation notice added to the README. No active PRs, issues, or commits are being processed.

Get running

git clone https://github.com/checkly/headless-recorder.git
cd headless-recorder
npm install
npm run serve

This starts vue-cli-service in watch mode for development. Load the extension in Chrome via chrome://extensions by pointing to the output directory.

Daily commands:

npm run serve        # Development mode with watch
npm run build        # Production build
npm run test:unit    # Run Jest tests
npm run lint         # Run ESLint

For local testing: After npm run serve, load the extension directory in Chrome's developer mode.

Map of the codebase

• package.json: Defines all dependencies, build scripts (vue-cli-service), and test setup; critical for understanding the deprecated versions pinned here.
• src/: Root directory for Vue components, content scripts, and state management — the core extension logic lives here.
• .github/workflows/lint-build-test.yml: CI pipeline showing how the extension is built and tested; helps understand the build output location and entry points.
• public/browser-extension.html: The HTML manifest/entry point for the browser extension popup UI.
• tests/: Jest test directory; shows test patterns and coverage for the codebase (though sparse for a deprecated project).
• jest.config.js: Jest configuration including Vue 3 preprocessor setup (@vue/vue3-jest), necessary to run tests locally.
• babel.config.js: Babel configuration for transpiling Vue 3 and ES6+ to browser-compatible code; required for the build pipeline.

How to make changes

Event recording logic: src/ for content script listeners and event handlers. UI components: src/components/ (Vue SFC files) for popup/panel interface. Code generation: search for Playwright/Puppeteer template logic in the state management files. Selectors & DOM traversal: @medv/finder and css-selector-generator libraries handle this. Tests: __tests__/ for Jest specs. Start by adding an event type to the recorder or tweaking selector generation if you want to extend functionality.

Traps & gotchas

Node version sensitivity: Built with older Vue CLI and Babel versions (2020 era); may fail on Node 18+. Dual state management: Both Pinia and Vuex are installed — understand which is actively used to avoid conflicts. CSS selector fragility: The extension relies on @medv/finder for selector generation, which can produce brittle selectors on dynamic pages. Extension reload: Changes require manual extension reload in Chrome's developer tools; watch mode does not auto-reload the extension. Deprecated dependency versions: Playwright 1.10.0 and Puppeteer 9.0.0 are from 2021 and may not work with modern websites or support newer browser APIs.

Concepts to learn

• Content Scripts (Chrome Extension API) — The extension injects content scripts into web pages to listen for DOM events; understanding how they communicate with the popup via message passing is central to how the recorder works.
• CSS Selector Generation — The extension uses @medv/finder to auto-generate CSS selectors for clicked elements; this is critical to producing maintainable Playwright/Puppeteer scripts.
• State Management (Pinia / Vuex) — The extension uses both Pinia and Vuex to track recording state, captured interactions, and generated code; understanding the state flow is key to modifying logic.
• Vue 3 Composition API — The extension is built on Vue 3; the components use the newer Composition API pattern, not the legacy Options API.
• Browser Event Listeners & DOM Traversal — The recorder captures click, change, keydown, submit events via native JavaScript listeners in the content script and traverses the DOM to find selectors.
• Code Generation & Template Literals — The extension builds Playwright and Puppeteer scripts as strings using template literals and state snapshots; understanding the generation logic is needed to add new event types.
• Page Load Detection (Navigation Events) — The extension distinguishes between load and unload events to insert waitForNavigation() clauses; this is critical for reliable script execution.

Related repos

• microsoft/playwright — The primary target framework for generated scripts; understanding Playwright's API is essential to understanding what this extension produces.
• puppeteer/puppeteer — The alternate target framework for generated scripts; this extension supports both Playwright and Puppeteer output.
• puppeteer/replay — Google's official successor to browser interaction recording; a maintained alternative if this extension's deprecation is a blocker.
• cypress-io/cypress — Competitor browser automation framework with built-in recording features; relevant for users exploring alternatives to Playwright/Puppeteer.
• checkly/checkly-cli — Companion tool from the same maintainer (Checkly) for running synthetic monitoring; the extension can export scripts directly to Checkly.

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for src/assets and src/tests/helpers.js utilities

The repo has minimal test coverage. The tests directory only contains build.spec.js and helpers.js, but there are no tests for core recording logic, selector generation (css-selector-generator), or finder utilities (@medv/finder). Given the extension records browser interactions and generates scripts, testing the selector/locator generation is critical for reliability.

• [ ] Create src/tests/selectors.spec.js to test css-selector-generator integration and fallback logic
• [ ] Create src/tests/finder.spec.js to test @medv/finder usage for robust element identification
• [ ] Expand src/tests/helpers.js with tests for any DOM manipulation or event handling utilities
• [ ] Update jest.config.js and jest.setup.js if needed to support browser extension testing patterns
• [ ] Ensure test:unit script runs and reports >70% coverage for src/ directory

Migrate from Vuex 4 + Pinia beta to Pinia stable (v2.0+)

The package.json shows both Vuex 4.0.2 and Pinia 2.0.0-beta.3. Pinia is now the official Vue 3 state management library (Vuex is in maintenance mode). This tech debt migration will modernize the codebase, reduce bundle size, and improve maintainability. Given the deprecated status, this could be a good learning PR for contributors understanding the codebase's state architecture.

• [ ] Upgrade pinia to latest stable (>2.1.0) in package.json
• [ ] Identify all Vuex store files in src/ (likely src/stores or similar) and convert to Pinia stores
• [ ] Remove Vuex 4.0.2 dependency and any Vuex plugins from main.js/App.vue
• [ ] Update all components using mapState/mapActions to use Pinia composition API or useStore()
• [ ] Run npm run test:unit to ensure state management refactor doesn't break existing tests
• [ ] Document the migration in CHANGELOG.md

Add missing localization strings to public/_locales/en/messages.json and create test validation

The project has i18n infrastructure (public/_locales/en/) but there's no test or build-time validation that all UI strings in src/ components are registered in messages.json. As a Chrome extension, missing translations cause broken UI. This PR adds both validation tests and documentation of required message keys.

• [ ] Create src/tests/i18n.spec.js to scan Vue components for chrome.i18n.getMessage() calls
• [ ] Extract all message keys from regex pattern matching and validate they exist in public/_locales/en/messages.json
• [ ] Add any missing common strings (e.g., 'pause', 'play', 'record', 'stop') to messages.json with proper descriptions
• [ ] Add pre-commit hook or lint rule to lint-build-test.yml workflow to prevent missing i18n strings in future PRs
• [ ] Document i18n contribution guidelines in CONTRIBUTING.md with the expected messages.json structure

Good first issues

• Add tests for the CSS selector generation logic (using @medv/finder and css-selector-generator) in __tests__/ — currently uncovered by Jest specs.
• Update the Playwright and Puppeteer script templates to support newer syntax (e.g., modern locator() API in Playwright) as a documentation-only patch to warn users about version gaps.
• Create a contribution guide document explaining how to add a new recorded event type (e.g., focus, blur, input) to the content script and corresponding code generator.

Top contributors

• [@Ignacio Anaya](https://github.com/Ignacio Anaya) — 62 commits
• @dependabot[bot] — 20 commits
• [@Nacho Anaya](https://github.com/Nacho Anaya) — 11 commits
• @pilimartinez — 3 commits
• @GregorKikelj — 1 commits

Recent commits

• 4fb93c1 — chore: add issue link (Nacho Anaya)
• 3240947 — chore: deprecation notice 🥲 (Nacho Anaya)
• e10522b — chore: privacy policy typo (#218) (GregorKikelj)
• 9091ad3 — build(deps): bump eventsource from 1.1.0 to 1.1.1 (#211) (dependabot[bot])
• b0b6a3c — build(deps): bump async from 2.6.3 to 2.6.4 (#207) (dependabot[bot])
• b87bea3 — build(deps): bump minimist from 1.2.5 to 1.2.6 (#205) (dependabot[bot])
• 25ce34d — build(deps): bump url-parse from 1.5.7 to 1.5.10 (#199) (dependabot[bot])
• 492c788 — build(deps): bump nanoid from 3.1.22 to 3.3.1 (#192) (dependabot[bot])
• 8c2f9f0 — build(deps-dev): bump jest from 27.2.5 to 27.5.1 (#189) (dependabot[bot])
• 76400f6 — build(deps): bump follow-redirects from 1.14.1 to 1.14.9 (#190) (dependabot[bot])

Security observations

• Critical · Deprecated Project - No Longer Maintained — README.md, Project Status. The project is officially deprecated as of December 16, 2022 with no maintenance, support, or security updates expected. This creates significant security risks as vulnerabilities will not be patched. Fix: Do not use this project in production. Migrate to actively maintained alternatives for browser automation testing and recording.
• High · Outdated Vue.js Dependencies with Known Vulnerabilities — package.json - dependencies and devDependencies. Vue 3.0.6 (released April 2021) and associated tooling contain known vulnerabilities. The project uses very old versions of vue-cli-service (4.5.0), @vue/test-utils (2.0.0-rc.6), and other core dependencies that are no longer receiving security patches. Fix: Update all Vue.js related packages to latest stable versions. Run 'npm audit' to identify and fix known vulnerabilities. Consider using automated dependency updates with Dependabot (already configured).
• High · Vulnerable Puppeteer and Playwright Versions — package.json - devDependencies (puppeteer@9.0.0, playwright@1.10.0). Puppeteer 9.0.0 and Playwright 1.10.0 are severely outdated (from 2021). These versions likely contain multiple known security vulnerabilities, especially for handling untrusted browser content. Fix: Update to latest stable versions of Puppeteer and Playwright. These tools interact with browser content and should always be kept current for security.
• High · Vulnerable Lodash Version — package.json - dependencies (lodash@4.17.21). While lodash@4.17.21 is recent, older versions had prototype pollution vulnerabilities. Ensure no dangerous lodash functions are used without proper input validation, especially with user-controlled data. Fix: Review code for use of vulnerable lodash functions like _.defaultsDeep() with untrusted input. Consider using lodash/fp or alternative libraries.
• High · Outdated Build Tools and Babel Configuration — package.json - devDependencies (babel-core, eslint, prettier). Babel 7.0.0-bridge.0 (deprecated bridge version), ESLint 6.7.2, and Prettier 1.19.1 are all severely outdated and no longer receive security updates. Fix: Update all build tools to current versions. Use modern Babel 7+ configuration, ESLint 8+, and Prettier 2+.
• Medium · Potential XSS Risk in Vue 3 Application — package.json - dependencies (vue3-highlightjs@1.0.5), src/components (likely code display components). While Vue 3 escapes by default, the project uses vue3-highlightjs (1.0.5) for code highlighting, which could be vulnerable if displaying user-generated code without proper sanitization. Fix: Ensure all user-supplied code being highlighted is properly sanitized. Use libraries like DOMPurify if displaying any untrusted HTML. Keep vue3-highlightjs updated.
• Medium · Chrome Extension Security Concerns — src/content-scripts, src/background, package.json. The extension interacts with browser content and DOM. The use of @medv/finder (2.0.0) for CSS selector generation and css-selector-generator (3.0.1) could be vulnerable to DOM-based attacks if not properly sandboxed. Fix: Implement strict Content Security Policy in manifest.json. Validate all DOM operations. Ensure content scripts properly sandbox user interactions. Review manifest.json permissions for least privilege.
• Medium · Missing npm Lock File Verification — .npmrc, package-lock.json, .github/workflows. While package-lock.json exists, with many outdated dependencies, there's risk of supply chain attacks. No clear evidence of lock file integrity verification in CI/CD. Fix: Enable npm package signature verification. Use 'npm ci' instead of 'npm install' in CI/CD pipelines. Consider npm audit fixes in automated workflows.
• Low · Outdated — undefined. undefined Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.