---
name: verify-widget-flow
description: Verify the Shopify or WooCommerce upload guide, saved-photo confirmation, localized error recovery and processing animation and result comparison through the real widget App in a local browser.
---

# Widget flow verification

## Launch

Use Node 22+, installed widget dependencies, and Chrome. From the repository root:

```sh
export PATH=/tmp/issue54-tools/node_modules/node/bin:$PATH
node .cursor/skills/verify-widget-flow/run.mjs --doctor
node .cursor/skills/verify-widget-flow/run.mjs /tmp/widget-flow-proof-$(basename "$PWD")
```

The executable helper builds the production App, components, translations and styles into scratch files. It mounts App through its public config, owns an OS-assigned loopback port, and waits for HTTP 200. Shopify resolves Playwright from the WordPress sibling; override `PLAYWRIGHT_MODULE` with an installed `@playwright/test` directory elsewhere. Override `CHROME_PATH` if Chrome is not `/usr/bin/google-chrome`. Recording needs Playwright's ffmpeg runtime. Runs have isolated ports, profiles and storage; choose distinct evidence directories.

## Doctor

`--doctor` loads the build and browser libraries, checks Chrome exists, and prints production source hashes. On a drive failure, run doctor again before a fresh helper invocation. Do not attach to a prior browser. The normal run also checks its owned HTTP server and locates the real confirmation controls.

## Drive

Read [the feature map](features/README.md). The helper serially exercises widths 390, 320 and 1280 in English and Italian. WordPress runs all six scenarios in both merchant and demo mode (12 total); Shopify runs six result scenarios. Demo mode uses public `config.demo: true` and checks the remaining quota, result actions, share control and saved gallery look after comparison. It seeds a saved synthetic photo through browser storage, clicks the real trigger, closes and reopens, and confirms the photo. It advances the browser clock by 4.1 seconds to observe the real loader timers, returns a structured error at the API boundary, chooses another photo, uploads an actual local PNG, confirms, receives a retryable rejection, retries and receives a result. It then drives the Before/After slider with keyboard, mouse and mobile touch, switches to garment comparison and back, and verifies split persistence without another generation.

Only the external HTTP generation boundary is substituted. No internal setters or test-only endpoints are used. All traffic outside the owned loopback origin is blocked and recorded as failure. Three mocked requests per scenario are counted; zero requests are required before confirmation. No store access or paid generation occurs. This verifies the real App compiled in an isolated fixture, not merchant configuration or physical camera hardware.

For WordPress also run `cd widget-src && npm run test:browser` to test the rebuilt shipped bundle and bootstrap, including widget-recovery, share and size/cart paths. Shopify's full gate has no browser step. In both repos run `python3 scripts/quality_gate.py`; the gate's clean-commit guard will remain unsatisfied when the owner requires uncommitted changes. Report that separately without weakening the guard.

## Evidence

The output contains `verification.json` with source hashes, layout measurements, API counts and results, plus screenshots of confirmation, processing, error, guide, before-after, compare and the demo gallery, browser videos, and traces. Inspect `390-en-guide.png` against the approved option B image and `320-it-guide.png` for wrapping. Each example label must fit inside the viewport, the modal must have no horizontal overflow, and mobile controls must retain their styles under the Vela global button rules. Trace files retain the actual action sequence. Browser page errors and external requests must both be zero.

## Cleanup

The helper closes only its own browser and server and removes its scratch bundle in `finally`, including failed runs. Evidence remains. Confirm `verification.json`, `390-en-guide.png`, `390-en-before-after.png`, `320-it-compare.png`, `390-en-trace.zip`, `demo-390-en-before-after.png`, `demo-320-it-compare.png`, `demo-390-en-gallery.png` and `videos/*.webm` survive. Never remove failure evidence as cleanup.

## Helpers

`run.mjs [OUTPUT_DIRECTORY|--doctor]` is executable. Keep common verification behavior aligned across repositories. The WordPress helper additionally drives its demo-only branch; Shopify has no separate demo result view. Use `/maintain-verification-skill` when the mapped flows change.