Open-source event management and ticket selling platform β perfect for concerts, conferences, and everything in between ποΈ If you find this project helpful, please consider giving us a star βοΈ
Hi.Events E2E Suite
End-to-end tests driving the real application (Laravel backend + SSR frontend + Postgres + Redis + Mailpit) with Playwright. Data is arranged through the REST API and flows are exercised through a real browser.
Layout
e2e/
βββ playwright.config.ts Config: baseURL, reporters, retries, artifacts
βββ fixtures/ Test fixtures (the extension point)
β βββ account.fixture.ts Registers + verifies an account (SaaS-aware)
β βββ auth.fixture.ts Builds the auth-cookie storage state
β βββ index.ts `test` / `expect` with all fixtures merged
βββ api/ Typed API client for arranging data
β βββ api-client.ts Auth helpers + authorized ApiClient
β βββ factory.ts Composable seeders (live event + product, β¦)
β βββ types.ts
βββ pages/ Page objects (thin, role/label/testid locators)
βββ utils/ env, unique ids, mode guards, Mailpit client
βββ tests/ Specs, grouped by feature
βββ auth/ registration
βββ events/ event creation
βββ checkout/ free + Stripe checkout
βββ box-office/ door sales: management + PIN, cash/comp/other/free
tenders, discounts and price overrides, questions,
sessions, orders tab, scan tab, card (Stripe-gated)
βββ management/ promo codes, questions, messages,
check-in lists, webhooks, editing a ticket
Every spec asserts on real page content after the action (the created item appears in its list/table, the edited value shows), not just a URL change.
Running the tests
Hermetic stack (identical to CI) β one command
run-e2e.sh starts the stack behind nginx on http://localhost:8123, migrates,
provisions the superadmin, installs dependencies, and runs the suite.
Locally it reuses a running healthy stack by default (fast iteration) and leaves it up afterwards; a missing or broken stack is recreated cleanly. In CI every run recreates the stack from scratch.
./e2e/run-e2e.sh # reuse (or create) the stack, run everything
./e2e/run-e2e.sh --fresh # force a clean stack recreation first
./e2e/run-e2e.sh --teardown # tear the stack down after the run
./e2e/run-e2e.sh --skip-stack # run against an already-running stack (e.g. dev)
./e2e/run-e2e.sh --skip-deps # skip npm ci / browser install (fast re-runs)
./e2e/run-e2e.sh -- --grep @smoke # pass args through to `playwright test`
Reuse caveat: docker compose up never rebuilds images. After changing
backend/ or frontend/ source, rebuild before running:
docker compose -f docker/e2e/docker-compose.e2e.yml build backend frontend
./e2e/run-e2e.sh --fresh
The hermetic stack is designed to run alongside the dev stack β it uses nginx on
8123 and Mailpit on 8225 (the dev stack uses 8443/8025), and nothing else is
published to the host. If those two ports are also taken, remap them:
E2E_HTTP_PORT=9123 E2E_MAILPIT_PORT=9225 \
E2E_BASE_URL=http://localhost:9123 MAILPIT_URL=http://localhost:9225 \
./e2e/run-e2e.sh
Manual (if you want to drive the steps yourself)
docker compose -f docker/e2e/docker-compose.e2e.yml up -d --wait
docker compose -f docker/e2e/docker-compose.e2e.yml exec backend php artisan migrate --force
cd e2e
npm ci
npx playwright install --with-deps chromium
npx playwright test
docker compose -f docker/e2e/docker-compose.e2e.yml down -v
Against the running dev stack
The suite is data-isolated (unique emails per run), so it can target the dev stack directly β useful for testing uncommitted changes without rebuilding the hermetic images (the dev stack mounts source live). Note it leaves test data behind in the dev database.
E2E_SAAS_MODE=true is required: the dev stack requires email verification, and the account
fixture only confirms the code from Mailpit in SaaS mode. That also means a queue worker must
be running to deliver the verification emails, and superadmin-dependent specs need the e2e
superadmin provisioned once:
cd docker/development
docker compose -f docker-compose.dev.yml exec -d backend php artisan queue:work
docker compose -f docker-compose.dev.yml exec backend php artisan dev:bootstrap \
[email protected] --password='SuperAdminPass123!'
Public order creation and promo-code lookup are rate limited per IP (APP_PUBLIC_ORDER_RATE_LIMIT_PER_MINUTE, default 60;
APP_PUBLIC_PROMO_CODE_RATE_LIMIT_PER_MINUTE, default 10); the suite runs from one IP, so set both high (e.g. 100000) in backend/.env first.
Seating and box office specs need APP_LICENCE_KEY=development in backend/.env. Add it yourself: no install gets it by default, and without it there are no Enterprise features, even on APP_ENV=local. The dev stack ignores the X-Hi-Licence-Simulation header, so specs that simulate a licence state β including the Hi.Events Cloud feature-flag specs β only really run on the hermetic stack and skip or fail here.
Then run specs directly (from e2e/), or the whole suite via the script (from the repo root):
E2E_BASE_URL=https://localhost:8443 MAILPIT_URL=http://localhost:8025 E2E_SAAS_MODE=true \
npx playwright test tests/events/recurring-event-checkout.spec.ts
E2E_BASE_URL=https://localhost:8443 MAILPIT_URL=http://localhost:8025 E2E_SAAS_MODE=true \
./e2e/run-e2e.sh --skip-stack --skip-deps
Handy scripts
npm test # run everything
npm run test:ui # Playwright UI mode (great for authoring)
npm run test:headed # headed browser
npm run test:smoke # only @smoke-tagged specs
npx playwright test --config tests '\.unit\.spec\.ts$' # pure-logic unit specs, no stack needed
npm run report # open the last HTML report
npm run typecheck # tsc --noEmit
Configuration
Copy .env.example to .env to override defaults. All are optional.
| Variable | Default | Purpose |
|---|---|---|
E2E_BASE_URL |
http://localhost:8123 |
Public entry point of the stack under test |
MAILPIT_URL |
http://localhost:8225 |
Mailpit HTTP API, for email assertions (8225 so it coexists with the dev stack's 8025) |
E2E_SAAS_MODE |
false |
Must match the backend's APP_SAAS_MODE_ENABLED |
STRIPE_PUBLIC_KEY |
(unset) | Stripe test-mode key; when unset the @stripe specs skip |
E2E_STRIPE_CONNECT_ACCOUNT_ID |
(unset) | An enabled Stripe Connect test account (acct_β¦) linked to each organizer by the seated card specs on a SaaS stack; they skip without it |
E2E_COMPOSE_FILE |
(per stack) | Compose file whose pgsql service utils/db.ts runs SQL in |
E2E_DB_USER |
(per stack) | Postgres user for utils/db.ts |
E2E_DB_NAME |
(per stack) | Postgres database for utils/db.ts |
Direct database helpers
A few states can't be reached through the API in test time (e.g. a checkout reservation
running out). utils/db.ts covers these by running SQL through
docker compose exec -T pgsql psql β expireOrder(shortId) moves an order's
reserved_until an hour into the past. It targets the hermetic stack
(docker/e2e/docker-compose.e2e.yml, hievents/hievents_e2e) by default and the dev stack
(docker/development/docker-compose.dev.yml, username/backend) when E2E_BASE_URL is on
port 8443; override with the three variables above. Specs using it need the Docker CLI on the
machine running Playwright.
Stripe specs
Tests that talk to the real Stripe test-mode API are tagged @stripe (paid checkout,
decline/retry, refund) and skip unless STRIPE_PUBLIC_KEY is set. The stack must be
booted with the keys (the backend needs STRIPE_SECRET_KEY, the frontend gets the
publishable key via compose) β setting them only at test time is not enough.
Easiest: put the test-mode keys in e2e/.env (gitignored; see .env.example) β
run-e2e.sh loads it and passes them to the stack:
./e2e/run-e2e.sh --fresh --skip-deps -- --grep @stripe
(--fresh only the first time, so the containers boot with the keys; after that the
reused stack keeps them.) Exported shell vars take precedence over e2e/.env.
Writing a new spec
- Import the shared harness:
import { test, expect } from '../../fixtures'; - Arrange data through the API β reach for
api/accountfixtures and thefactoryseeders rather than clicking through setup UI. - Drive the flow under test with a page object; assert in the spec, not the page object.
- Tag fast, load-bearing checks with
{ tag: '@smoke' }.
import { test, expect } from '../../fixtures';
import { createLiveEventWithFreeTicket } from '../../api/factory';
test('example', { tag: '@smoke' }, async ({ page, api, account }) => {
const event = await createLiveEventWithFreeTicket(api, account.organizerId);
// β¦drive the browser, then assertβ¦
});
Fixtures
account(worker-scoped) β a registered, verified account with an organizer and an authorizedApiClient. Handles SaaS-mode email verification automatically.api(worker-scoped) β the authorizedApiClient(alias ofaccount.api).authedPageβ aPagepre-authenticated asaccountvia injected auth cookie (no UI login). Use it for organizer-facing flows.pageβ the default unauthenticated page. Use it for public flows (checkout).mailpitβ client for asserting on outbound email.publicApiβ anonymous API context rooted at the API base URL, for buyer-side public endpoints (api/public-client.ts: create/complete orders, join waitlist, β¦).freshAccountβ a brand-new account + organizer isolated to this test, withnewAuthedPage()for browsing as that account.adminApi/superAdminPageβ authenticated as the superadmin thatrun-e2e.shprovisions viaphp artisan dev:bootstrap. If no superadmin exists (e.g.--skip-stackagainst a stack that never provisioned one), these skip the test locally and hard-fail in CI so admin coverage can't silently disappear.
Which isolation level to use:
- Event-scoped spec (products, orders, attendees, β¦) β shared
account+ a fresh event per test via thefactory. - Organizer-aggregate assertion (reports, settings, organizer webhooks, events list
contents) β
createFreshOrganizer(api)β one API call, still on the shared account. - Account/auth-level mutation (team invites, password change, messaging tier,
impersonation target) β
freshAccount.
Don't default to freshAccount β worker-sharing the account is the main reason the
suite is fast.
Selector policy
Prefer getByRole / getByLabel β Mantine emits real <label> associations and the
default English (Lingui) strings are stable. data-testid is configured
(testIdAttribute: 'data-testid'); add them to frontend source for interactive
elements the suite drives β buttons (open-modal, submit), menu items, and custom
widgets with no accessible label (e.g. CustomSelect, whose dataTestId prop lands
on its target and auto-derives <id>-option-<value> on each option). Convention:
kebab-case <feature>-<element>. Don't add IDs to text inputs with a unique label β
use getByLabel(/^Label/) (anchored regex dodges Mantine's required *). See the
test ID rules in .claude/rules/frontend/ui.md.
Watch for two things when asserting on list content: Mantine's Truncate hides the
full text in a tooltip past its length limit (assert a short value, or target the
visible node), and transient success toasts briefly contain the same text (target the
specific row/heading, e.g. getByRole('heading', { name }), not bare getByText).
SaaS mode
The suite is SaaS-aware but runs against non-SaaS by default (E2E_SAAS_MODE=false).
To run against a SaaS stack, bring the stack up with E2E_SAAS_MODE=true (sets the
backend's APP_SAAS_MODE_ENABLED) and run with E2E_SAAS_MODE=true. The account
fixture then pulls the verification PIN from Mailpit and confirms the email before use.
SaaS-mode Stripe specs need E2E_STRIPE_CONNECT_ACCOUNT_ID: an enabled Stripe Connect test
account (acct_β¦) belonging to the platform whose STRIPE_SECRET_KEY the stack uses. The specs
link it to each organizer in the database (enableStripePayments) and skip without it.
Known gap: in SaaS mode the message composer hides its form behind "Connect Stripe to enable messaging" until the account is manually verified, so composer-driven specs only run on a non-SaaS stack.
CI
.github/workflows/e2e.yml builds the backend and frontend images (GHA layer cache),
starts the stack, runs migrations, provisions the superadmin, and executes the suite.
The HTML report, traces, and stack logs are uploaded as artifacts on every run.
Lanes:
- Pull requests run the
@smokelane only (--grep @smoke) against a self-hosted stack: one fast, load-bearing check per feature area. Tag discipline matters: exactly one@smoketest per area. - Pushes to
main/develop, a nightly cron (03:00 UTC) and manual runs (workflow_dispatch) run the full suite twice, against a self-hosted stack (E2E_SAAS_MODE=false) and a SaaS stack (E2E_SAAS_MODE=true), each sharded across two parallel jobs with their own hermetic stack. - Adding the
full-e2elabel to a PR forces the full lane on that PR. - Every run, pull requests included, also runs all
*.unit.spec.tsfiles in a stack-lesse2e unit specsjob (npx playwright test --config tests '\.unit\.spec\.ts$'), so pure-logic specs don't need an@smoketag.
A final summary job merges every shard's results.json (via scripts/github-summary.mjs)
into one report on the run's summary page (and as a PR comment): a pass/fail table per
mode, each failure with its error, the tests that only passed on retry, jobs that never
produced a report, and why tests were skipped.
Repository secrets (all optional; the specs that need them skip without them, keeping fork PRs green):
| Secret | Used for |
|---|---|
STRIPE_TEST_PUBLIC_KEY, STRIPE_TEST_SECRET_KEY |
Stripe test-mode keys for the @stripe specs |
E2E_STRIPE_CONNECT_ACCOUNT_ID |
@stripe specs on the SaaS stack (see SaaS mode) |