Onboarding: segment-boneyard/nightmare

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/segment-boneyard/nightmare 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

AVOID — Stale and unlicensed — last commit 2y ago

• 40+ active contributors
• Distributed ownership (top contributor 27% of recent commits)
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ No license — legally unclear to depend on
• ⚠ No CI workflows detected

_{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 segment-boneyard/nightmare repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/segment-boneyard/nightmare.

What it runs against: a local clone of segment-boneyard/nightmare — 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 segment-boneyard/nightmare | Confirms the artifact applies here, not a fork | | 2 | Default branch master exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 776 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>segment-boneyard/nightmare</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of segment-boneyard/nightmare. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/segment-boneyard/nightmare.git
#   cd nightmare
#
# 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 segment-boneyard/nightmare and re-run."
  exit 2
fi

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

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

# 4. Critical files exist
test -f "lib/nightmare.js" \\
  && ok "lib/nightmare.js" \\
  || miss "missing critical file: lib/nightmare.js"
test -f "lib/actions.js" \\
  && ok "lib/actions.js" \\
  || miss "missing critical file: lib/actions.js"
test -f "lib/runner.js" \\
  && ok "lib/runner.js" \\
  || miss "missing critical file: lib/runner.js"
test -f "lib/ipc.js" \\
  && ok "lib/ipc.js" \\
  || miss "missing critical file: lib/ipc.js"
test -f "lib/frame-manager.js" \\
  && ok "lib/frame-manager.js" \\
  || miss "missing critical file: lib/frame-manager.js"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 776 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~746d)"
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/segment-boneyard/nightmare"
  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

Nightmare is a high-level browser automation library built on Electron that exposes a synchronous-feeling API (goto, type, click, evaluate) for automating browser interactions and UI testing. It replaces PhantomJS with Electron under the hood, offering roughly 2x performance improvement and modern JavaScript engine support. Core use cases are web scraping, task automation on non-API sites, and UI test automation. Single-package structure: lib/nightmare.js is the main entry point exposing a Promise-based API; lib/actions.js contains user interaction methods (click, type, goto); lib/runner.js manages script execution; lib/preload.js injects code into Electron renderer process; lib/ipc.js handles main↔renderer communication via Electron IPC. Test fixtures in test/fixtures/ organize test HTML files by feature (navigation/, evaluation/, manipulation/, etc.). Electron runs headlessly or with GUI depending on configuration.

Who it's for

QA engineers and automation developers who need to test web UIs programmatically, and web scraping developers who want a higher-level abstraction over raw Electron APIs without callback hell. Users appreciate the synchronous-feeling chaining API for writing readable test scripts.

Maturity & risk

Abandoned—the README explicitly states 'This library is no longer maintained.' Built in 2014-2018 era when PhantomJS dominated; Segment moved on from active development. The project has comprehensive test coverage (test/ directory with fixtures and CircleCI CI/CD setup), but no recent commits visible. Not recommended for new projects; consider Puppeteer or Playwright instead.

High risk for new projects: unmaintained since ~2018, relies on Electron 2.0.18 (released 2018) which is severely outdated with known security vulnerabilities, no active maintainer to patch security issues in dependencies. README includes a 'Security Warning' about undiscovered Electron vulnerabilities allowing malicious sites to execute code. Single historical maintainer (Segment team) means no community safety net.

Active areas of work

Nothing—this is a dormant repository in the Segment boneyard. No active PRs, issues, or commits are being processed. The 3.0.2 version was the final release.

Get running

Clone and test locally: git clone https://github.com/segment-boneyard/nightmare.git && cd nightmare && npm install && npm test (or make test via Makefile). Requires Node.js ≥4.0.0 and will download Electron 2.0.18 on first run.

Daily commands: make test runs the full test suite via Mocha; node example.js runs the basic example (though example.js path is listed but contents not shown). Tests require an HTTP test server (built into test setup via Express fixtures).

Map of the codebase

• lib/nightmare.js — Main entry point and core Nightmare class orchestrating the browser automation lifecycle
• lib/actions.js — Defines all public user-facing actions (goto, click, type, etc.) that comprise the API
• lib/runner.js — Manages the Electron child process lifecycle and IPC communication with the renderer
• lib/ipc.js — Handles inter-process communication protocol between main and renderer processes
• lib/frame-manager.js — Manages frame/iframe navigation and context switching for multi-frame page automation
• lib/preload.js — Preload script injected into renderer context to provide DOM automation primitives
• package.json — Declares Electron 2.0.18 dependency and all runtime/build tooling requirements

Components & responsibilities

• Nightmare (lib/nightmare.js) (Node.js, Promises) — Public API facade; maintains action queue, coordinates lifecycle, provides chainable interface
  • Failure mode: Action queue deadlock; unhandled rejection in promise chain; missed cleanup on error
• Runner (lib/runner.js) (child_process, EventEmitter) — Spawns and manages Electron child process; routes IPC messages to/from actions; enforces action sequencing
  • Failure mode: Process spawn failure; IPC timeout; stale child process on crash without cleanup
• Preload (lib/preload.js) (Electron preload, DOM APIs) — Runs in renderer context; interprets action messages; manipulates DOM; evaluates user JavaScript
  • Failure mode: Script injection errors; DOM selector not found; timing race on dynamic content; frame context mismatch
• Frame Manager (lib/frame-manager.js) (iframe APIs, window references) — Tracks iframe/frame context; switches navigation scope; maintains window references across frame boundaries
  • Failure mode: Cross-origin frame access blocked; stale frame references after reload; frame count mismatch
• IPC (lib/ipc.js) (JSON, child_process messaging) — JSON-RPC style serialization/deserialization; marshals action arguments and results between processes
  • Failure mode: Circular reference serialization; unserializable argument types; message loss on process crash

Data flow

• User script → Nightmare API — User calls .goto(url).click(selector); returns chainable Promise-like object
• Nightmare API → Action queue (Runner) — Each action method pushes {type, args, timeout} to queue
• Runner queue processor → IPC (child_process.send) — Dequeues action, serializes to JSON, sends to Electron renderer via IPC
• IPC message → Preload script listener — Renderer process receives IPC message, parses action type and args
• Preload script → Browser DOM — Executes action handler (e.g., querySelector + click); evaluates user code in page context
• Preload handler completion → IPC reply (child_process.send) — Serializes result/error, sends back to main process
• IPC reply → Runner promise resolver — Main process receives result, resolves or rejects action promise, triggers next queued action
• Resolved action → User promise chain — Action promise settles; user's .then() executes or chain continues to next action

How to make changes

Add a new automation action

1. Define the action handler in lib/actions.js by adding a method that queues an action object with type, args, and optional timeout (lib/actions.js)
2. Implement the corresponding renderer-side logic in lib/preload.js that handles the action type and manipulates the DOM (lib/preload.js)
3. Add test cases in test/index.js that verify the action works against test fixtures in test/fixtures/ (test/index.js)

Handle a new IPC message type

1. Add encoder/decoder logic in lib/ipc.js for the new message format and register handlers (lib/ipc.js)
2. Wire message routing in lib/runner.js to dispatch to action queue or state manager (lib/runner.js)
3. Add corresponding renderer handler in lib/preload.js to listen and respond to the IPC event (lib/preload.js)

Support a new frame/iframe automation scenario

1. Extend frame detection and context tracking logic in lib/frame-manager.js (lib/frame-manager.js)
2. Update preload.js to inject frame isolation and cross-frame reference resolution (lib/preload.js)
3. Add test fixture HTML with iframes in test/fixtures/navigation/ and corresponding test case (test/fixtures/navigation/valid-frame.html)

Why these technologies

• Electron 2.0.18 — Provides Chromium rendering engine with full modern DOM/JS APIs; headless equivalent to PhantomJS but ~2x faster and actively maintained
• Node.js IPC (child_process) — Enables main-process control of renderer via message passing; isolates automation logic from browser context
• Preload script injection — Grants controlled access to renderer DOM without exposing Node.js APIs; security boundary between orchestrator and page

Trade-offs already made

• Synchronous-looking API via promise chaining instead of callbacks

  • Why: Improves readability and reduces callback nesting for test scripts
  • Consequence: Internal queueing required; action execution is still asynchronous but sequential

• Single Electron process per Nightmare instance

  • Why: Simplifies state management and frame context handling
  • Consequence: Cannot parallelize multiple browser sessions in same process; heavy memory footprint for concurrent scripts

• Preload script for DOM manipulation instead of CDP

  • Why: Avoids Chrome DevTools Protocol overhead; direct DOM access faster for most operations
  • Consequence: Limited to Electron/Chromium; cannot use Nightmare with Firefox or Safari

Non-goals (don't propose these)

• Multi-process parallelization within a single Nightmare instance
• Real-time WebSocket or streaming event capture
• Browser compatibility beyond Electron (Firefox, Safari, IE)
• Native mobile automation (iOS/Android)
• Complex form filling with file uploads and drag-drop
• WebDriver protocol compatibility

Traps & gotchas

Electron 2.0.18 requires libXvfb on Linux CI (test/bb-xvfb script); tests expect a local HTTP server from test fixtures. The lib/preload.js injects code into the renderer before page load, which breaks if Content-Security-Policy headers are strict—some legacy sites may not be automatable. IPC communication in lib/ipc.js is brittle to large payloads or long response times; no timeouts visible in the code.

Architecture

Concepts to learn

• Electron Main Process ↔ Renderer Process IPC — Nightmare's entire architecture depends on this pattern (lib/ipc.js)—you must understand that user scripts run in Node's main process but browser automation happens in Electron's renderer process, with bidirectional message passing between them
• Preload Scripts — lib/preload.js injects JavaScript into the renderer before page load to enable evaluate() and form interaction; understanding preload security and timing is essential for debugging why evaluate() calls fail on certain pages
• Promise Chaining & Async Sequencing — Nightmare chains promises to create a synchronous-looking API (lib/runner.js manages this); understanding how .then() chains are queued via enqueue library is key to debugging timing and race conditions in test scripts
• Headless Browser Automation — Core Nightmare use case; differs from unit testing because it tests the full rendering pipeline, timing, and real user interactions—Electron's headless mode is critical for CI/CD compatibility
• Frame/Iframe Isolation — lib/frame-manager.js handles cross-origin and same-origin iframes; CSS selectors and evaluate() calls behave differently in iframes—testing this is one of Nightmare's harder use cases and a common source of bugs
• XPath and DOM Selector Evaluation — Nightmare uses XPath internally (not just CSS selectors) via lib/actions.js to locate elements; understanding when XPath vs CSS is used affects click(), type(), and visible() reliability
• Cookie & Session Persistence — test/fixtures/cookies/ tests show Nightmare stores Electron cookies on disk; understanding Electron's cookie jar and persistence is needed for multi-page test sessions and crawling authenticated pages

Related repos

• puppeteer/puppeteer — Modern successor to Nightmare; uses headless Chrome/Chromium instead of Electron, actively maintained by Google, faster and more stable for UI automation
• microsoft/playwright — Cross-browser alternative supporting Chrome, Firefox, Safari; modern concurrent API with better reliability than Nightmare's Electron approach
• segmentio/niffy — Perceptual diffing tool built on top of Nightmare; used to detect UI regressions—direct companion project for visual testing
• segmentio/daydream — Chrome extension that generates Nightmare scripts by recording user interactions; complementary developer tool for Nightmare users
• electron/electron — Underlying Electron framework (v2.0.18 in package.json); Nightmare is a wrapper exposing Electron's browser automation via a higher-level API

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 comprehensive unit tests for lib/frame-manager.js

The frame-manager.js module handles iframe navigation and context switching, which is critical functionality for browser automation. Currently, the test directory contains fixtures for 'navigation/invalid-frame.html' and 'navigation/valid-frame.html' but there are no dedicated test files for frame-manager.js operations. This is a high-risk area that deserves explicit test coverage.

• [ ] Create test/unit/frame-manager.test.js with test cases for frame switching, frame validation, and error handling
• [ ] Add test cases covering: switchToFrame(), switchToParentFrame(), and invalid frame scenarios using the existing test/fixtures/navigation/*.html files
• [ ] Ensure tests cover both synchronous and asynchronous frame operations since the module handles IPC communication

Add test coverage for lib/ipc.js message handling and error scenarios

The ipc.js module handles inter-process communication between the main Electron process and renderer process, which is fundamental to Nightmare's architecture. There are no visible dedicated tests for IPC message routing, error propagation, or timeout handling. This module deserves explicit test coverage given its central role.

• [ ] Create test/unit/ipc.test.js to test message sending, receiving, and routing between processes
• [ ] Add test cases for error conditions: malformed messages, missing handlers, and communication timeouts
• [ ] Test the interaction between ipc.js and the preload.js bridge to ensure message serialization works correctly

Refactor lib/actions.js into module-specific files and add integration tests

lib/actions.js likely contains multiple action implementations (goto, click, type, etc.) in a single file. The file structure shows many fixtures (manipulation, events, cookies, evaluation) suggesting diverse action types. Splitting this into focused modules (e.g., lib/actions/navigation.js, lib/actions/interaction.js, lib/actions/evaluation.js) would improve maintainability and allow for targeted testing.

• [ ] Analyze lib/actions.js to identify logical groupings (navigation, DOM interaction, evaluation, cookies)
• [ ] Create lib/actions/ subdirectory with specific modules for each action category
• [ ] Create corresponding integration tests in test/actions/ using the existing fixture files (test/fixtures/manipulation/, test/fixtures/evaluation/, test/fixtures/cookies/) to verify each action type works correctly

Good first issues

1. Add end-to-end tests for lib/frame-manager.js (iframe handling)—no test/frame-manager-test.js file exists but the module is used, leaving iframe automation untested. 2. Document the preload.js injection mechanism in a comment block—the security/behavior implications of lib/preload.js are non-obvious to newcomers. 3. Add a test fixture and test case for robots.txt and sitemap.xml handling in navigation (common scraping use cases missing from test/fixtures/navigation/).

Top contributors

• @matthewmueller — 27 commits
• @reinpk — 12 commits
• @rosshinkley — 9 commits
• @stephenmathieson — 6 commits
• [@Zach Sierakowski](https://github.com/Zach Sierakowski) — 5 commits

Recent commits

• 0f47de8 — Update Readme.md (bsneed)
• b230e85 — misc formatting and update version in lock file (matthewmueller)
• af11432 — Release 3.0.2 (matthewmueller)
• 0bcd8f8 — Merge pull request #1534 from julianladisch/Chromium-FileReader-Vulnerability (matthewmueller)
• 98c842f — Electron 2.0.18 - Chromium FileReader Vulnerability Fix (CVE-2019-5786) (julianladisch)
• 0d76929 — feat: Adds support for custom user agents. (noopz)
• 0bd6dbc — bumps the version of electron to 2.0.2 (noopz)
• 25467e5 — Release 3.0.1 (matthewmueller)
• db82ef3 — bump electron (matthewmueller)
• f49265c — Update Readme.md (matthewmueller)

Security observations

Failed to generate security analysis.

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.