Integration testing

Microsoft Clarity Testing

Use this checklist to verify the read-only Clarity integration with package tests, dashboard/recording smoke checks, and one deliberate Data Export API request.

Protect the project token

The smoke script reads the token from CLARITY_API_TOKEN. Do not paste Clarity tokens into logs, tickets, screenshots, or shared notes.

1. Prerequisites

Microsoft Clarity project admin access.
A project-level Data Export API token generated under Settings - Data Export.
A non-sensitive project name for smoke output.
An optional project ID or internal label for metadata.

2. Live smoke

Run from the repo root without the Data Export leg first:

bash
CLARITY_API_TOKEN="..." \
CLARITY_PROJECT_NAME="Production AU" \
pnpm --filter @shopmcp/clarity-mcp smoke:live

This checks the tool registry, Microsoft documentation query, dashboard query, recordings endpoint, recording triage, and ecommerce scorecard.

3. Final production gate

Run the export leg once after the lighter smoke passes:

bash
CLARITY_API_TOKEN="..." \
CLARITY_PROJECT_NAME="Production AU" \
CLARITY_SMOKE_EXPORT=1 \
pnpm --filter @shopmcp/clarity-mcp smoke:live

The tool registry should report 9 read-only Clarity tools.
Documentation, dashboard, recordings, recording triage, and growth scorecard checks should pass.
clarity_get_live_insights should pass when CLARITY_SMOKE_EXPORT=1 is set.
If the export leg returns 429, wait for the Clarity quota reset before judging readiness.

4. Optional tuning

CLARITY_SMOKE_LOOKBACK_DAYS=1|2|3 controls the live-smoke window. Default: 1.
CLARITY_SMOKE_COUNT=1..25 controls recording sample count. Default: 5.
CLARITY_SMOKE_SCORECARD=0 skips the ecommerce scorecard leg.
CLARITY_PROJECT_ID stores a project ID in the smoke tenant context for metadata only.