End-to-End Testing
Relevant source files
The following files were used as context for generating this wiki page:
End-to-End (E2E) testing in the Nordcom Commerce project ensures that user-facing flows in both the apps/admin and apps/storefront applications function correctly from a real user's perspective. These tests drive the real application through a browser, interacting with the live deployment and a persistent or ephemeral local Convex backend. The primary objective is to validate complex workflows, such as CMS content authoring, media management, and multi-tenant routing, across various device viewports.
Sources: CLAUDE.md:120-123, apps/admin/playwright.config.ts:13-14
Testing Infrastructure
The E2E suite is built on Playwright and is integrated into the workspace via Turborepo. Tests are designed to be rerun-safe against a shared deployment by using unique run tokens (RUN_TOKEN) to prevent data collisions between test runs.
Core Configuration
The testing environment is configured to handle the specific needs of a multi-tenant Next.js application.
| Feature | Implementation |
|---|---|
| Framework | Playwright Test |
| Test Directory | e2e/ within each app directory |
| Browser Projects | Chromium (Desktop), and a responsive matrix (Foldable, Phone, Tablet) |
| Parallelism | Enabled (fullyParallel: true) |
| Retries | 2 retries in CI, 0 locally |
| Timeout | 60 seconds (Standard), 240 seconds (Web server startup) |
Sources: apps/admin/playwright.config.ts:16-52, CLAUDE.md:129-131
Data Flow and Environment
E2E tests interact with a real Next.js server and a Convex backend. Locally, this backend is typically an ephemeral or persistent instance booted via @nordcom/commerce-test-convex.
The diagram shows how Playwright triggers global setup to seed data and manage auth state before the spec interacts with the Next.js server and Convex backend.
Sources: CLAUDE.md:125-128, apps/admin/playwright.config.ts:60-75
CMS Editor Testing
A significant portion of the E2E suite focuses on the CMS editor within the Admin app. These tests validate the "Editor Form" engine, which manages nested data structures and localized content.
Validation Cycles
Tests follow a specific lifecycle to ensure data persistence and integrity:
- Creation/Binding: Accessing
/new/routes where the first autosave binds the document to a real ID. - Authoring: Interacting with native field shells (
[data-testid="field-<path>"]) and array/block widgets. - Autosave Quiescence: Waiting for the 2-second interval autosave to finish (ensuring "Saving..." is hidden).
- Round-trip Verification: Performing a page reload to ensure authored data persists and re-renders correctly.
- Publishing: Triggering the publish action and asserting that validation rules (like required titles) are enforced.
- Version Control: Verifying that published snapshots can be restored via the
/versions/route.
Sources: apps/admin/e2e/header-editor.spec.ts:12-20, apps/admin/e2e/pages-editor.spec.ts:12-21, CLAUDE.md:127-128
Wait for Autosave Logic
Because the "Last saved" indicator is sticky, the testing harness uses a polling mechanism to ensure the form is clean before proceeding with a reload or publish action.
The sequence diagram illustrates the robust polling strategy used to ensure a "clean" form state by waiting for the autosave interval to quiesce.
Sources: apps/admin/e2e/header-editor.spec.ts:47-65, apps/admin/e2e/pages-editor.spec.ts:77-95
Specialized Test Flows
Responsive Layouts
Tests with the .responsive.spec.ts suffix are executed across a device matrix. They validate the SplitEditorLayout, ensuring that the fields and preview panes adapt correctly (stacking on mobile, side-by-side on desktop) and that the footer toolbar remains on-screen.
Sources: apps/admin/e2e/editor-responsive.responsive.spec.ts:13-22, apps/admin/playwright.config.ts:20-21
Media and Uploads
E2E tests exercise the full media pipeline. This includes:
- Uploading real binary files (e.g., 1x1 or 64x64 PNGs).
- Triggering the Sharp-based image derivative pass.
- Editing metadata (Alt text, focal points) in the media dialog.
- Committing the selection to a document field.
Sources: apps/admin/e2e/pages-editor.spec.ts:40-43, apps/admin/e2e/media-picker.spec.ts:13-18
Multi-tenant Routing
Tests verify that the Next.js middleware correctly resolves tenants by domain and enforces authentication.
- Tenant Resolution: Driving the app using
E2E_SHOP_DOMAIN(e.g.,nordcom-demo-shop.com). - Auth Gates: Asserting that unauthenticated requests to protected settings routes redirect to the login page.
Sources: apps/admin/e2e/shop-settings.spec.ts:25-29, CLAUDE.md:89-92
Summary
The End-to-End testing strategy relies on Playwright to provide high-confidence validation of the project's most critical paths. By simulating real user interactions against a live environment—including complex CMS authoring, media processing, and responsive layout transitions—the suite ensures that the multi-tenant architecture remains robust and performant across all supported devices.