Validation
Validate presentation timing, measurement, and live versus controlled evidence.
A standalone host can validate the published browser bundle before a full application integration. Use fixture tests for deterministic UI checks and authenticated API tests for live data and persistence.
Prerequisites
- Mount the widget with Quick start.
- Record the loaded bundle version and configured API environment without recording member credentials.
- Prepare a test member with catalog access and at least one identified recent search.
- Provide test product routes and a chat assistant for callback acceptance.
Standalone host checks
Run panel mode first, then recreate the widget with onSearchSubmit for host mode.
Use browser request inspection and host callback counters to distinguish the two modes.
| Check | Expected result |
|---|---|
| Click or focus the field | One open request; the panel opens after the host applies state |
| Open with a blank query | Recents and recommendations load from the pre-search endpoint |
| Type, then replace the query quickly | Suggestions appear after the pause; stale results never replace the latest query |
| Submit in panel mode | Catalog request, visible products, and one schema-valid event after commit |
| Submit a successful zero-result query | Empty state, count 0, and outcome empty |
| Submit in host mode | One callback and closure. One event only after that host calls presented |
| Select a recommended or catalog product | One typed product callback and closure |
| Select a THEO prompt or Ask AI | One seed callback and launcher activation; chat opens once when wired |
| Clear the input | Pre-search returns without deleting persisted recents |
| Remove an identified recent | Dismissal request and refresh; the item remains absent after reload |
| Resize 768 → 767 → 768 pixels | Overlay → sheet → overlay with automatic presentation |
| Force either presentation | Resizing keeps the explicitly chosen presentation |
| Destroy during an outstanding request | No stale UI or completion callback after destruction |
Authentication and failure checks
| Case | Expected result |
|---|---|
| Blank token | Local auth failure; no API request |
| Invalid token | At most one 401 retry with a newly read token; one auth error notification |
| Repeated failures | No repeated auth notification until a request succeeds |
| Restore a valid session and retry | The failed section recovers |
| One pre-search section unavailable | That section shows recovery while the other remains usable |
| Catalog unavailable | Failure state with recovery, rather than a successful empty result |
| Dismissal write fails | Recents recovery; retry does not submit a query or open chat |
| Inspect emitted events | No bearer or raw query. Performed keyword is sanitized and at most 200 |
Search measurement
Count an event only after the matching products or empty state are visible. Fetch completion, router completion, and loading placeholders are not enough. Retained cards from the previous query are not the new result. Validate each envelope with the locked official events package. See Concrete outcomes.
| Check | Expected result |
|---|---|
| Typed submit with products | One schema-valid event after the page commits |
| 535 matches, 15 shown | resultCount 15, not 535; outcome success |
| Suggestion selection | Keyword is the selected term, not the prefix |
| Committed empty state | Count 0 and outcome empty |
| Failed request | Error or retry UI, and no performed event |
| Recoverable retry commits | One event on the same execution |
| Cancel, then submit again | Old handle inert; new execution may emit |
| Repeat the same query | Distinct execution; a second event is allowed |
| Supersede with another query | Old navigation, fetch, and commit are ignored |
| Close panel during host load | Measurement remains eligible |
| Leave the results route | Captured execution is cancelled |
| Duplicate commit or page 2 | No extra performed event |
| 201-character query | Event keyword is canonical and at most 200 |
| Fully redacted query | No performed event; the raw query is unchanged |
| Invalid page or count | TypeError; a corrected report can still emit |
In-memory handles require the shell and SDK to survive navigation. A full document load cannot keep the handle. Do not accept a host that unloads the SDK unless a transfer is implemented and evidenced.
Evidence labels
Label every additional run authenticated-live or controlled.
Live means the deployed host and published bundle, with a real member session.
Controlled means fixtures, a local bundle, or an injected catalog.
A controlled pass does not prove staging delivery.
Record source revision, loaded bundle identity, route, execution id, displayed count, event count, and schema result.
Record empty, repeat, cancellation, retry, and long or redacted cases with that label.
Do not record member credentials.
The sanitized keyword may be recorded as the analytics field.
The raw query and bearer must not.
A member with no recents can validate the empty state but cannot prove persisted dismissal. Use a seeded member and reload against the same live service to prove persistence. Fixture products and mock callbacks do not prove live catalog access, host routing, or chat integration.
Contributor harness
SDK contributors can run the bundled harness from a source checkout with Bun 1.4 installed. It builds the production IIFE before serving the host page.
cd packages/search-sdk
cp harness/.env.example harness/.env.localnpm run harnessOpen http://127.0.0.1:5179.
Restart the harness after source changes so it rebuilds the browser bundle.
Default mode uses in-process API fixtures and a mock bearer; it does not call a deployed API.
| Harness query switch | Test behavior |
|---|---|
presentation=auto, overlay, or sheet | Responsive default or a forced presentation |
results=panel or results=host | Panel results, or a host callback that is not itself presentation |
askAi=off | Launcher event and closure without a seed callback |
token= | Blank-token failure without a network request |
scenario=empty | Successful zero-row fixture responses |
scenario=catalog-unavailable | Catalog-only fixture failure |
scenario=typeahead-unavailable | Typeahead-only fixture failure |
Use the standalone host from Quick start for authenticated live testing.
Supply its member bearer through auth.getToken and your host session accessor.
Keep real member credentials out of query strings, saved URLs, and diagnostics.
The scenario switches affect fixtures only; they are not Search SDK or live API options.
The harness is controlled evidence.
It does not prove a deployed host.
Browser automation exercises the same built IIFE in desktop Chromium, mobile Chromium, and mobile Safari. From the Search SDK package folder:
npm run test
npm run test:e2eInstall the required browsers before the first automated run:
npm exec playwright install chromium webkitAcceptance evidence
Record version, environment, results ownership mode, viewport, callback counts, and pass/fail outcomes. Label that record live or controlled, as defined above. Capture sanitized request paths and screenshots for visual failures. Validate live product data, recent dismissal persistence, and chat handoff separately from fixture coverage. Complete the host route checks before handing integration responsibility to another team.
Related links
- Mount a standalone page: Quick start
- Wire real callbacks: Host integration
- Expected behavior: Functionality
- Diagnose failures: Troubleshooting