Deco Ecommerce QA

Do NOT batch edits via Write — every change must be a targeted Edit with surrounding context preserved.

Phase 3.5 — Doctor CORE-marker gate (setup-time, best-effort)

Goal: catch a missing/mis-placed CORE marker now, before opening a PR that looks green but reds in CI (REQ-01). The CORE markers are the 8 listed under CORE markers in "Canonical data-qa attributes" above.

qa doctor is a single-page reporter — Open the URL and report which data-qa-* slugs are present. It prints ✓ data-qa-<slug> — count=N … / ✗ data-qa-<slug> — missing for the page you give it and always exits 0 (it never fails on its own). So on the homepage it only sees the entry-page markers (category-link, cart-icon, often minicart); the deeper CORE markers (product-card, pdp-title, buy-button, minicart-checkout, checkout-page) are validated by the journey, which walks the flow and exits non-zero on a missing/mis-marked marker. Use both: doctor for a fast static read, the journey for the end-to-end verdict.

1. Decide local-boot feasibility (per references/ci-local-boot.md): the decofile must be committed at .deco/blocks/ (not gitignored) and the repo buildable. If infeasible — no committed decofile, Cloudflare-only preview, a Node/Bun repo with no local preview, or boot times out — skip cleanly: record doctor: deferred-to-CI (reason: <…>) for the PR body and proceed. The workflow doctor pre-step + journey are then the gate. (Holds in both modes.)
2. If feasible, boot locally (pre-warm deno cache dev.ts main.ts, then deno task build → deno task preview &, poll :8000) and run:
   • qa doctor --url http://localhost:8000 — capture the homepage marker table for the PR body.
   • qa journey --url http://localhost:8000 — the real end-to-end CORE gate. If the full journey can't complete locally (cross-origin VTEX checkout, or a checkoutUrlPattern that only matches the real domain), fall back to qa journey --url http://localhost:8000 --smoke (steps 1,2,3,5 — home → PLP → PDP → add-to-cart) and note in the PR body that minicart/checkout were not exercised locally.
   • Build a CORE-marker results table: slug → present / missing / satisfied-by-feature → where checked (doctor page or journey step).
3. Fail condition — a CORE marker missing (and not feature-satisfied), or the journey reds on a CORE step:
   • Interactive: STOP. Report the missing marker(s) + the offending page/step, loop back to Phase 3 to fix the JSX, and re-run this gate. Do not proceed to Phase 5.
   • (headless): proceed to Phase 5 but open a DRAFT PR flagged as failing (see Phase 5) with the doctor/journey results at the top of the body — never a normal green-looking PR.

Phase 4 — Scaffold config + workflows

Skip this phase entirely in AUGMENT mode. Pick template variants based on the runtime classification from Phase 1.

Common to all runtimes:

• .qarc.json (root) — scaffold platform-aware, don't ship it empty (REQ-03). Always set url, cep (01310-100 default), and viewports ["desktop","mobile"]. Then populate features / viewports from detection, logging each choice + a one-line rationale in the PR body:
  • Checkout shape — probe first: curl -sL -o /dev/null -w '%{url_effective} %{num_redirects}' <prod>/checkout. Same-origin (0 redirects, e.g. VTEX served at /checkout) → features.checkoutUrlPattern: "**/checkout**" (the store has no checkout DOM of its own to mark — don't rely on a data-qa-checkout-page you don't own). Cross-origin redirect → features.checkoutCrossOrigin: true. A deco-native checkout the store does own → keep data-qa-checkout-page, leave checkout features empty. Either checkout feature satisfies the CORE data-qa-checkout-page for the Phase 3.5 gate. See references/checkout-quirks.md Pattern 2.
  • Blocking overlay/popup (newsletter / cookie / age-gate / geolocation) detected in Phase 2 but with no clean ✕ to mark → features.dismissOverlaysHeuristic: true (prefer marking data-qa-dismiss; the heuristic is the documented fallback).
  • Two-level mobile drawer with no top-level leaf link (Phase 2.5 gotcha 3) → "viewports": ["desktop"]. Leave selectors empty unless a documented override applies (references/checkout-quirks.md).
• .qarc.json is only read if the repo is checked out (it loads from process.cwd()). The engine reads config from join(process.cwd(), ".qarc.json"). Without an actions/checkout step the file does not exist on the runner, so ALL config (features.checkoutUrlPattern, viewports, selectors) is silently ignored — the journey runs with only --url + defaults. The shipped templates already check out the repo; this warning matters for anyone writing a simplified manual workflow. Typical symptom: data-qa-checkout-page missing even though you set checkoutUrlPattern. (See references/decobot-preview-parsing.md.)
• .gitignore: append qa-output/.
• Doctor CORE-marker pre-step (REQ-01 durable gate). All four workflow templates run qa doctor --url "$TARGET_URL" before the journey and fail fast with a precise message if an entry-page CORE marker (data-qa-category-link or data-qa-cart-icon) is missing on the resolved target. qa doctor is single-page and always exits 0, so the step parses its ✓ … count=N / ✗ … — missing output and exit 1s itself; the journey step still gates the deeper markers (product-card, pdp-title, buy-button, minicart-checkout, checkout-page). This turns the most common setup failure — a missing/mis-marked category link, which otherwise reds cryptically at journey step 2 — into an early, named failure. Don't strip this step.
• Previews behind Cloudflare (engine ≥ 0.5.0). The PR workflow runs against the decobot *.decocdn.com preview, which is fronted by Cloudflare Bot Management — a CI datacenter-IP headless Chromium gets a 403/challenge instead of the store. The engine (≥ 0.5.0) tags its User-Agent with a deco-qa-bot/1.0 token so a one-time zone WAF carve-out can let the QA bot through without weakening protection for real users. Set it once at the Cloudflare zone (works for every deco store); see references/cloudflare-bot-allowlist.md. If you can't touch the zone, use a workflow_dispatch.url override or the Deno local-boot fallback below.
• Waiting for the prod deploy on main. A push to main only triggers deco's prod build/deploy, which runs asynchronously off GitHub Actions (minutes) — it is NOT a workflow or check-run, so there's nothing to needs:. If QA-main fires on push and hits prod immediately, it races the deploy and tests the previous version → false data-qa-*-missing failures. The fix (baked into both qa-main.yml templates): a Wait for deco prod deploy step polls the deco commit status Deco / <site> / prod (legacy status API) via getCombinedStatusForRef until it flips pending → success, then runs the journey; it fails fast on failure/error (with the build-logs link) and times out after 20 min. Gated on github.event_name == 'push' so workflow_dispatch overrides skip the wait. The context carries the per-store slug, so it's matched by pattern /^Deco \/ .+ \/ prod$/ (site-agnostic). This mirrors the PR workflow's Wait for deco preview. See references/decobot-preview-parsing.md.

Pure Node/Bun (or Mixed):

• .github/workflows/qa-pr.yml (from templates/workflows/qa-pr.yml.tmpl): triggers on pull_request + workflow_dispatch (manual URL fallback). Polls for deco preview comment (handles multiple bot logins + marker styles — see references/decobot-preview-parsing.md), runs bunx @decocms/qa@{{ENGINE_VERSION}} journey --url $PREVIEW_URL --junit junit.xml --github.
• .github/workflows/qa-main.yml (from templates/workflows/qa-main.yml.tmpl): triggers on push to main + workflow_dispatch. Waits for the deco prod deploy (polls the Deco / <site> / prod commit status until success) before running the engine against the prod URL — see "Waiting for the prod deploy on main" below.
• scripts/qa-local.sh: bunx @decocms/qa journey --url ${1:-http://localhost:8000} --headed --debug.
• package.json: add @decocms/qa as a devDep pinned to the exact {{ENGINE_VERSION}} (not latest / ^) + scripts qa:local, qa:smoke. Commit the lockfile so CI installs that exact build.

Pure Deno + Fresh:

• .github/workflows/qa-pr.yml (from templates/workflows/qa-pr-deno.yml.tmpl) and .github/workflows/qa-main.yml (from qa-main-deno.yml.tmpl). Same preview-link strategy as Node/Bun, but with Deno: denoland/setup-deno@v2.x, poll the decobot comment for the *.decocdn.com preview (secure bot-only filter — see references/decobot-preview-parsing.md), then deno task qa:run --url "$TARGET_URL". The main workflow also waits for the prod deploy commit status before running (see "Waiting for the prod deploy on main" above). The Playwright step derives the engine's chromium revision from the pinned version (npm view @decocms/qa@{{ENGINE_VERSION}} dependencies.playwright). {{ENGINE_VERSION}} (from Phase 1) is the only placeholder to fill — otherwise site-agnostic. workflow_dispatch.url overrides to hit any reachable URL (e.g. prod smoke).
  • Requires engine ≥ 0.5.0 + the Cloudflare carve-out (see the "Previews behind Cloudflare" note above). Without the deco-qa-bot allowlist the preview 403s the CI runner.
  • Fallback when you can't add the Cloudflare carve-out (no zone access): build & boot the storefront in CI (deno task build → deno task preview → --url http://localhost:8000) instead of polling the preview. Slower (cold deco builds re-fetch the module graph — pre-warm with deno cache) and needs the decofile committed at .deco/blocks/. See references/ci-local-boot.md for that workflow variant.
• deno.json: merge in tasks from templates/deno-tasks.json.tmpl (qa:local, qa:smoke, qa:run). qa:run / qa:smoke pin npm:@decocms/qa@{{ENGINE_VERSION}}; only qa:local keeps @latest (local debug). Commit deno.lock. qa:run may carry --timeout 20000 as headroom.
• Do NOT create package.json. Do NOT create scripts/qa-local.sh (tasks live in deno.json).

If pre-existing scripts qa:local/qa:smoke conflict: rename the skill's to deco-qa:local/deco-qa:smoke and update workflows accordingly. See references/coexistence-with-existing-tests.md.

Engine version pinning (deterministic CI). The journey verdict must be reproducible and attributable to store changes — never to engine drift. So every CI/verdict path pins the exact {{ENGINE_VERSION}} captured in Phase 1: the workflow journey commands, qa:run/qa:smoke, and the package.json devDep + committed lockfile (deno.lock for Deno). @latest is reserved for qa:local, where reproducibility doesn't matter and you want the newest build to debug against. Bump deliberately, never automatically: to adopt a newer engine, open a PR that bumps {{ENGINE_VERSION}} in the workflows + package.json/deno.json — the QA journey is that PR's gate, so you adopt the new engine only if the store stays green. A tool whose whole value is determinism cannot let a silent @latest release flip a store's verdict with no store-side change. (No Renovate/Dependabot — the bump is a human decision.)

Phase 5 — Open PR

• Create branch chore/setup-qa.
• Commit message: chore(qa): set up E2E suite with data-qa attributes.
• PR body: include the Phase 2 mapping table, list of modified files, debug instructions (bun run qa:local), link to engine docs. If an existing suite already walks the same purchase funnel (weak text/class selectors, minicartOpen-style assertion — see references/coexistence-with-existing-tests.md), add the overlap heads-up so the team can drop the redundant funnel-walk and keep only its perf-metrics. Never edit that suite — flag only.
• PR body — additive sections (REQ-01/02/03), in both modes. Beyond the items above, include: (a) Doctor CORE-marker results — the 8-slug table from Phase 3.5, headed with its source (setup-time local boot vs deferred-to-CI — local boot infeasible: <reason>; add the --smoke-only caveat if minicart/checkout weren't exercised locally); (b) Gotcha findings — the four Phase 2.5 verdicts as verdict + file:line + action taken; (c) Traced add-to-cart path — the resolved file:line → … → useCart().addItems(...) chain (+ any dead file skipped); (d) .qarc.json features chosen + rationale — each populated features / viewports entry with its one-line cause.
• Always apply the qa-setup label to the PR. It is the source of truth the Phase 1 idempotency pre-check reads (gh pr list --label qa-setup --state open) — the branch name and title are not. A PR without this label will not de-duplicate against a future run.
• STOP before git push and gh pr create. Ask the user to confirm. Modifying source code + opening a PR has high blast radius. Never auto-push. A standing "don't ask, just ship it" / "I trust you, open the PR" does NOT authorize the push — under time pressure especially, still show the diff + the PR body and get an explicit yes for this push. (Local commits on the chore/setup-qa branch are fine; the gate is the push/PR.) This confirmation gate applies in interactive mode only.

(headless) — push + PR are authorized by the mode itself. The onboarding/CI flow set QA_SETUP_MODE=headless to run setup end-to-end, and the PR is the human gate — so no interactive confirmation. (The Phase 1 idempotency pre-check has already guaranteed this isn't a duplicate.) Run exactly this sequence:

1. Branch. Use chore/setup-qa. If the remote branch already exists (git ls-remote --exit-code --heads origin chore/setup-qa), append a unique suffix from the commit: chore/setup-qa-<shorthash> (git rev-parse --short HEAD).
2. Commit with the message above.
3. Ensure the label exists (idempotent — ignore "already exists"): gh label create qa-setup --color 0E8A16 --description "QA setup PR" || true
4. Push + open the PR with the label: gh pr create --label qa-setup --title "chore(qa): set up E2E suite with data-qa attributes" --body "<body>" where <body> = the Phase 2 mapping table + list of modified files + bun run qa:local debug instructions + engine-docs link + the additive sections (Doctor CORE-marker results, the four Gotcha findings, the traced add-to-cart path, the .qarc.json features + rationale) + (if any) the LOW-confidence TODO list from Phase 2 and the decobot-absent → qa-main.yml-only note from Phase 1.

(headless) — if the Phase 3.5 doctor gate FAILED (a CORE marker missing on a feasible local boot): still run steps 1–3, but in step 4 open the PR as a flagged-failing draft instead of a normal PR. Add a second label and the --draft flag, and put the doctor/journey results at the TOP of the body:

• gh label create qa-doctor-failed --color B60205 --description "QA setup blocked: CORE marker missing" || true
• gh pr create --draft --label qa-setup --label qa-doctor-failed --title "[QA SETUP — DOCTOR FAILED] chore(qa): set up E2E suite with data-qa attributes" --body "<doctor/journey results first, then the normal body>"

This surfaces the broken setup for a human without shipping a green-looking PR, and the Phase 1 doctor-failed draft exception keeps a re-run from treating it as a completed setup.

Phase 6 — Verify

Apply superpowers:verification-before-completion: do not declare success without observing the workflow run green.

• After PR is open: gh pr checks --watch.
• If checks pass: report JUnit link + success. Done.
• If checks fail: apply superpowers:systematic-debugging. Read gh run view --log-failed. Most common cause: missing or mis-marked data-qa-*. Identify which step of the journey failed, locate the missing element, edit + commit a fix. Do NOT patch in CI logs without re-reading the failing JSX.

Common mistakes

• Auto-editing without showing the Phase 2 table to the user. Always confirm before editing — JSX changes are PR-visible. (Interactive only; in headless mode auto-editing HIGH/MEDIUM is intended and the PR is the review point — see the Phase 2 (headless) note.)
• Using Write instead of Edit. Write loses surrounding context. Always Edit.
• Marking PLP product card's buy button with data-qa-buy-button. That's a quick-add on the card, not the PDP CTA. Distinguish: data-qa-buy-button is PDP-only.
• Over-marking a generic nav-item component as data-qa-category-link. When the header renders institutional links, dropdown triggers AND category links through one component (e.g. NavItem.tsx) with identical markup, marking the generic anchor tags ALL of them. findSelector picks the first [data-qa-category-link] in DOM order — usually the institutional one → a product-less page → enter-pdp fails with data-qa-product-card missing (a misleading symptom; the real cause is the category link). A .qarc.json selectors override does not fix it — findSelector tries the raw [data-qa-*] first and only falls back to selectors[slug] when the attribute exists nowhere; since it exists (on several links) the override is ignored. Fix at the JSX source: gate the attribute so only real PLP links get it (discriminator is store-specific, e.g. href?.includes("sort=")). See references/category-link-disambiguation.md. (Learning: aviator.)
• Assuming external components forward data-*. Verify by reading typings or testing in browser. If unsure, wrap.
• Variant-gated buy button → empty cart → "minicart-checkout not found" (engine-version-dependent). The right marking depends on the engine's add-to-cart order, so check the version:
  • Engine ≥ 0.5 (the common case): the buy step pre-selects the variant first — it finds data-qa-variant-option, clicks an in-stock size, and only then clicks an already-enabled data-qa-buy-button. Marking the size options (in-stock only, every render branch) is sufficient; data-qa-variant-confirm is not required here.
  • Older click-buy-first order (and genuine modal "confirm" flows): the engine clicked data-qa-buy-button first, while still disabled → no-op → never re-clicked. There, mark the buy button with BOTH data-qa-buy-button and data-qa-variant-confirm (it doubles as the post-variant confirm). Don't misdiagnose the empty cart as a VTEX/localhost issue — it adds to cart fine locally once variant-confirm is set. (Learning: Osklen.)
  • See data-qa-conventions.md for the version-tagged step order and references/checkout-quirks.md Pattern 6.
• Assuming a green journey means the cart actually filled. Historically the journey asserted clicks, NOT cart state — so an emptied/wrong-quantity/wrong-price cart passed green. The pinned engine (≥ 0.5.x) asserts cart state natively: mark the cart-state slugs (data-qa-minicart-item* etc.) and the journey fails the verdict on a broken cart. No companion scripts — just the markers (see references/cart-state-gates.md).
• Editing the wrong add-to-cart file (dead code). Before assuming a file matters, grep for imports and trace what data-qa-buy-button actually executes. A sdk/useAddToCart.ts is often dead code; the real path is usually a local hook in AddToCartButton/common.tsx whose onAddItem comes from a platform wrapper (AddToCartButton/vtex.tsx) where the real useCart().addItems({ quantity }) lives. A "break" in the dead file is a no-op — and proves nothing about the tests.
• Two-level mobile drawer. If the mobile drawer's top-level items open submenus instead of linking to PLPs, step 2 can't find a category link (engine opens only one level) — scope .qarc.json to "viewports": ["desktop"].
• Wrong checkout mode. Run curl -sL -o /dev/null -w '%{url_effective} %{num_redirects}' STORE.com/checkout first: same-origin (0 redirects, VTEX served at /checkout) → the store has no DOM of its own to mark, so the clean default is features.checkoutUrlPattern: "**/checkout**" (don't try to mark a marker that isn't yours); a selectors["data-qa-checkout-page"]="#checkoutMainContainer" is the documented alternative when you'd rather assert VTEX's stable DOM hook. Cross-origin redirect → features.checkoutCrossOrigin: true. (See checkout-quirks.md Pattern 2.) Note: a /checkout?orderFormId=test returning 403 outside the journey is normal (no session/orderForm) — inside the journey, with a real cart, the URL matches the pattern.
• A restricted permissions: block silently breaks actions/checkout. GitHub Actions grants full default scopes only when no permissions: block exists; declaring one drops every scope not listed. So a block like permissions: { pull-requests: read } removes the default contents: read and checkout fails with repository not found (git exit 128). Always declare contents: read plus the scopes each job actually needs (PR workflow: `pull-r

…(truncated)