94 lines
3.0 KiB
Markdown
94 lines
3.0 KiB
Markdown
# Pipeline Spec (WE-P)
|
|
|
|
## Overview
|
|
|
|
Orchestrates the full evaluation pipeline for a single URL. Accepts a URL, runs
|
|
screenshot capture, Lighthouse audits, and DOM analysis in sequence, writes all
|
|
outputs to a configured directory, and exits with a clear success or failure code.
|
|
|
|
## Responsibilities
|
|
|
|
- Parse and validate input (URL + output directory)
|
|
- Execute pipeline stages in order: screenshot → lighthouse → DOM → report
|
|
- Write all output files to the configured output directory
|
|
- Exit 0 on success, exit 1 on any stage failure (with error to stderr)
|
|
|
|
Delegates to: `screenshot.js`, `lighthouse.js`, `dom-analysis.js`, `report.js`
|
|
|
|
## Dependencies
|
|
|
|
None — this is the root spec. All other specs depend on this one for the I/O contract.
|
|
|
|
## Data Model
|
|
|
|
### Input
|
|
|
|
```
|
|
CLI: node src/index.js <url>
|
|
ENV: TARGET_URL=<url> (fallback if no CLI arg)
|
|
ENV: OUTPUT_DIR=/output (default: /output)
|
|
```
|
|
|
|
### Output directory layout
|
|
|
|
```
|
|
$OUTPUT_DIR/
|
|
report.md ← primary artifact
|
|
screenshots/
|
|
desktop.png
|
|
mobile.png
|
|
raw/
|
|
lighthouse-desktop.json
|
|
lighthouse-mobile.json
|
|
dom.json
|
|
```
|
|
|
|
## Requirements
|
|
|
|
**WE-P-1:** The URL must be provided as the first CLI argument or via `TARGET_URL`.
|
|
If neither is present, print usage to stderr and exit 1.
|
|
|
|
**WE-P-2:** The URL must start with `http://` or `https://`. If it does not, print
|
|
an error and exit 1.
|
|
Why: Lighthouse and Playwright both require a valid HTTP URL. Silent failures with
|
|
invalid URLs are confusing.
|
|
|
|
**WE-P-3:** The output directory (default `/output`) and its subdirectories
|
|
(`screenshots/`, `raw/`) must be created if they do not exist.
|
|
Why: The Docker volume mount only creates the parent; subdirs must be explicit.
|
|
|
|
**WE-P-4:** Pipeline stages run sequentially in this order:
|
|
1. Screenshots + DOM extraction (single Playwright browser session)
|
|
2. Lighthouse desktop audit
|
|
3. Lighthouse mobile audit
|
|
4. Report assembly
|
|
Why: Lighthouse requires its own Chrome instance. Running screenshots and DOM
|
|
extraction first in a single Playwright session is more efficient than two sessions.
|
|
|
|
**WE-P-5:** Each pipeline stage logs a single progress line to stdout before starting
|
|
(e.g., `"Capturing screenshots..."`).
|
|
|
|
**WE-P-6:** If any stage throws, the error message is printed to stderr and the
|
|
process exits 1. Partial output files are acceptable — the caller should check
|
|
exit code, not file presence.
|
|
|
|
**WE-P-7:** On success, print the path to `report.md` and exit 0.
|
|
|
|
## Scenarios
|
|
|
|
### Scenario: Happy path
|
|
**Given:** Valid URL `https://example.com` and writable `/output`
|
|
**When:** Pipeline completes all stages
|
|
**Then:** Exit 0; `report.md`, `screenshots/desktop.png`, `screenshots/mobile.png`,
|
|
`raw/lighthouse-desktop.json`, `raw/lighthouse-mobile.json`, `raw/dom.json` all exist
|
|
|
|
### Scenario: Missing URL
|
|
**Given:** No CLI arg and `TARGET_URL` not set
|
|
**When:** `index.js` starts
|
|
**Then:** Prints usage to stderr, exits 1
|
|
|
|
### Scenario: Invalid URL scheme
|
|
**Given:** URL `file:///etc/passwd`
|
|
**When:** Validation runs
|
|
**Then:** Prints error "URL must start with http:// or https://", exits 1
|