docs: plan live parser tests

docs/superpowers/specs/2026-04-30-live-parser-tests-design.md

@@ -0,0 +1,37 @@
+# Live Parser Tests Design
+
+## Summary
+
+Add explicit live endpoint tests for each core scraper parser path. These tests are excluded from normal deterministic test commands and run only through a dedicated package script.
+
+## Scope
+
+- Add one live suite per parser: eBay, Kijiji, Facebook.
+- Place suites under `packages/core/test/live/` so normal `bun test packages/core/test/*.test.ts` patterns do not include them accidentally.
+- Add a root `test:live` script that runs all live suites together.
+- Keep existing mocked tests unchanged.
+
+## Behavior
+
+- Each suite calls the public scraper entry point for that marketplace with a narrow query and low max item count.
+- Assertions verify scrape output shape and parser viability, not exact listing identity.
+- eBay and Kijiji require live network access and fail on endpoint/parser breakage.
+- Facebook is strict: missing or expired `FACEBOOK_COOKIE` fails the live suite instead of skipping.
+
+## Test Data
+
+- Use stable broad Canadian queries such as `iphone` or `laptop` to reduce empty-result risk.
+- Use low limits to avoid unnecessary load and rate-limit pressure.
+- Avoid exact prices, titles, listing IDs, or ordering assumptions.
+
+## Failure Meaning
+
+- Empty result arrays fail because live parser logic did not produce usable listings.
+- Missing required fields fail because adapter contracts depend on those fields.
+- Authentication failures fail for Facebook because selected scope is strict.
+
+## Verification
+
+- Normal suite remains offline: `bun test packages/core/test`.
+- Live suite runs by explicit script: `bun run test:live`.
+- Full static checks remain via `bun run ci`.