Skip to main content
The storefront ships two test layers: fast unit/integration tests with Vitest, and a browser end-to-end suite with Playwright that runs against a real Spree backend booted in Docker.

​
Unit & integration (Vitest)

​
End-to-end (Playwright)

The E2E suite drives a browser against a real Spree backend. npm run e2e:up boots the backend — Postgres, Redis, and the official ghcr.io/spree/spree:latest image from e2e-backend/docker-compose.yml — then seeds it and mints an API key through the official @spree/cli (spree seed, spree sample-data, spree api-key create), installed as a dev dependency. No create-spree-app setup is required.
The checkout test pays with card 4242 4242 4242 4242 through Stripe’s test mode. PaymentIntents land in whichever Stripe test account owns the keys you exported.

​
CI

In CI, set STRIPE_SECRET_KEY as a repository secret and STRIPE_PUBLISHABLE_KEY as a repository variable (Settings → Secrets and variables → Actions). The E2E job skips itself on fork PRs, where GitHub never exposes repository secrets.

​
Testing against a customized backend

By default the E2E suite runs against the stock official Spree image (ghcr.io/spree/spree:latest), so it verifies the storefront against a vanilla Spree — not a backend with your own extensions, serializers, or seed data.
The E2E stack reads a SPREE_IMAGE env var and falls back to the stock image when it’s unset. Set it to any image that exposes the Store API on the container’s port 3000, and the suite runs against that backend instead.

​
Your own Spree image

If you already publish a customized Spree image:

​
A create-spree-app project’s backend

A project scaffolded with create-spree-app has its customizable Spree in backend/ (built from backend/Dockerfile) and this storefront in apps/storefront/. Build that backend into a local image and point the suite at it — this is what tests the storefront against the exact Spree you deploy, extensions and all:
New create-spree-app projects wire this into the generated storefront CI workflow automatically — the workflow builds backend/Dockerfile and runs the storefront E2E against that image rather than stock Spree.

​
Interactive / manual

To click through the storefront against a running backend (no E2E harness), point it there directly: set SPREE_API_URL and SPREE_PUBLISHABLE_KEY in .env.local (see Environment Variables) and run npm run dev.