# Landing Page Pre-Flight Auditor

A Playwright-powered auditor that answers a practical paid-media question:

> Is this landing page technically safe to put ad spend behind?

The tool opens any URL in a real Chromium browser, captures client-observable evidence, classifies ad/analytics tags, attempts the primary ecommerce action when product/cart structure is present, compares product truth against tracking payloads, and emits a stakeholder-ready HTML report plus raw technical artifacts.

## Why This Matters

Most pixel checks stop at "did a tag fire?" This auditor goes further:

- Did the page load cleanly in a real browser?
- Which tracking providers actually fired?
- Did Add to Cart work?
- Did conversion-like tracking fire after the user action?
- Did tracked price/currency/product/variant match what the customer saw?
- Are duplicate events likely to inflate measurement?
- What could not be verified safely?

## Demo Proof

Live GitHub Pages view:

- <https://vasubansal7576.github.io/landing-page-preflight-auditor/>

Primary assignment target:

- Neeman's product page: <https://neemans.com/products/duoform-sneakers-for-men-ecru>
- Tracked sample report: [sample_report/20260617T153847Z-neemans-com.html](sample_report/20260617T153847Z-neemans-com.html)
- Latest live run summary: [AD_CANDIDATE_AUDITS.md](AD_CANDIDATE_AUDITS.md)

Additional ecommerce proof:

- Brooklinen product page: <https://www.brooklinen.com/products/luxe-core-sheet-set>
- Result: `READY WITH CAUTION`
- Report and screenshot are included in [AD_CANDIDATE_AUDITS.md](AD_CANDIDATE_AUDITS.md)

## Quick Start

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m playwright install chromium
```

Run an audit:

```bash
python run_audit.py --url "https://neemans.com/products/duoform-sneakers-for-men-ecru"
```

Run with the optional Groq duplicate-event judge:

```bash
GROQ_API_KEY=... python run_audit.py \
  --url "https://neemans.com/products/duoform-sneakers-for-men-ecru" \
  --llm-duplicates
```

## Outputs

Each run creates:

- `sample_report/<run_id>.html` - stakeholder report
- `sample_report/<run_id>.json` - machine-readable summary
- `sample_report/<run_id>_assets/*.png` - portable report screenshots
- `artifacts/<run_id>/network.jsonl` - captured network log
- `artifacts/<run_id>/dom_snapshots.json` - before/after DOM evidence
- `artifacts/<run_id>/raw_audit.json` - raw browser capture
- `artifacts/<run_id>/trace.zip` - Playwright trace
- `artifacts/<run_id>/network.har` - HAR evidence
- `artifacts/<run_id>/screenshot_full.png`
- `artifacts/<run_id>/screenshot_after_interaction.png`
- `artifacts/<run_id>/judgment_log.jsonl` when `--llm-duplicates` is used and an ambiguous duplicate needs model review

## Verdicts

- `READY`: no blockers, high-risk findings, watch items, or unverifiable critical checks.
- `READY WITH CAUTION`: no blockers/high-risk findings, but watch or unverified items remain.
- `NOT READY`: at least one blocker or high-risk measurement/interaction issue.

Finding severities:

- `BLOCKER`
- `HIGH RISK`
- `WATCH`
- `PASS`
- `UNVERIFIED`

## Scope

Universal checks run for every URL:

- navigation status and final URL
- console/page errors
- failed critical browser requests
- known tracking provider detection
- page/product-view style event detection
- duplicate tracking request detection
- screenshot, HAR, trace, and JSON evidence

Deep ecommerce checks run when product/cart structure is detected:

- visible and structured product truth
- Shopify product JSON, JSON-LD, cart forms, variant/SKU
- Add-to-Cart interaction
- post-click conversion-like event detection
- price/currency/product/variant payload correspondence
- event timeline and payload correspondence tables

If ecommerce structure cannot be inferred safely, the report says `UNVERIFIED` instead of pretending.

## LLM Boundary

The deterministic analyzer produces the report by default. Groq is optional and only used via `--llm-duplicates` for ambiguous duplicate/event-intent classification. The model never decides whether requests happened, whether numeric values match, or what the final verdict is. Every attempted model judgment is logged with timestamp, model, input, prompt, and output.

## Project Map

- [ARCHITECTURE.md](ARCHITECTURE.md) - system design and data flow
- [SUBMISSION.md](SUBMISSION.md) - reviewer guide
- [COMPLETION_AUDIT.md](COMPLETION_AUDIT.md) - requirement-by-requirement evidence
- [AD_CANDIDATE_AUDITS.md](AD_CANDIDATE_AUDITS.md) - Neeman's and Brooklinen live-run summaries with screenshots
- [NOTES.md](NOTES.md) - implementation trade-offs and assumptions
- [scope.md](scope.md) - production expansion scope

## Verification

```bash
python3 -m unittest discover -s tests
python3 -m compileall -q auditor tests run_audit.py
python run_audit.py --url "https://neemans.com/products/duoform-sneakers-for-men-ecru"
```

## Demo Video

No video file is currently included in the repository. The submission includes browser-rendered report screenshots, HTML reports, JSON summaries, HAR files, and Playwright traces generated by live runs.