feat(e2e): lazy app init + playwright sharding for integration tests

[jacekradko]

Summary

• Refactors integration test app initialization to be lazy (on-demand) instead of eager (all upfront in global setup)
• Each app now initializes only when a test first needs it, via test.beforeAll in testAgainstRunningApps
• Uses file-based locking to prevent multiple Playwright workers from initializing the same app concurrently
• Adds Playwright native sharding support via PLAYWRIGHT_SHARD env var
• Splits nextjs integration tests (the CI critical path) into 3 shards per Next.js version

How it works

Before: Global setup starts ALL 13 next.appRouter.* apps in parallel → every test waits for all apps → 8 min total
After: Each shard only initializes the ~4-5 apps its tests actually need → 3 shards run in parallel → ~3-4 min critical path

Lazy init flow

1. test.beforeAll calls app.init()
2. init() checks if app is already running (state file + health check)
3. If not, acquires a file-based lock (atomic wx flag)
4. Double-checks state file after lock (another worker may have finished)
5. Performs full init (clerk setup → commit → install → build → serve)
6. Writes to state file so other workers can adopt

Sharding

• Playwright config reads PLAYWRIGHT_SHARD env var (e.g., "1/3")
• CI matrix splits nextjs tests into 3 shards per Next.js version (6 total entries)
• Each shard only builds the apps its tests actually reference

Test plan

• Verify integration tests pass without sharding (backward compatible — PLAYWRIGHT_SHARD unset returns undefined)
• Verify sharded nextjs tests pass in CI
• Confirm each shard only initializes the apps it needs (check logs for Starting full init vs Adopted from state file)
• Verify non-nextjs integration tests are unaffected

Summary by CodeRabbit

• Tests

  • Enabled parallel test execution with sharding support across multiple CI workers to improve testing efficiency.
  • Implemented inter-worker coordination to prevent redundant test initialization and ensure consistent state.

• Chores

  • Updated test infrastructure configuration to support distributed test runs.
  • Streamlined HTTP server initialization flow during testing.

[changeset-bot]

🦋 Changeset detected

Latest commit: 50a5db7

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Mar 10, 2026 3:27am

[pkg-pr-new]

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@8019

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@8019

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@8019

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@8019

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@8019

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@8019

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@8019

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@8019

@clerk/express

npm i https://pkg.pr.new/@clerk/express@8019

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@8019

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@8019

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@8019

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@8019

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@8019

@clerk/react

npm i https://pkg.pr.new/@clerk/react@8019

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@8019

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@8019

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@8019

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@8019

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@8019

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@8019

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@8019

commit: 50a5db7

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: fc7c5432-ee48-4d81-92e3-15c6a618b39b

📥 Commits

Reviewing files that changed from the base of the PR and between 766ae5b and 50a5db7.

📒 Files selected for processing (9)

• .changeset/lazy-app-init-sharding.md
• .github/workflows/ci.yml
• integration/models/longRunningApplication.ts
• integration/playwright.config.ts
• integration/scripts/index.ts
• integration/scripts/processLock.ts
• integration/testUtils/testAgainstRunningApps.ts
• integration/tests/global.setup.ts
• turbo.json

---

📝 Walkthrough

Walkthrough

This pull request implements test sharding infrastructure and converts application initialization from eager to lazy evaluation. The CI workflow is extended to run integration tests across three shards for Next.js versions 15 and 16, with shard context propagated via environment variables and artifact naming. A new file-based process locking mechanism coordinates initialization across concurrent workers. Application initialization is refactored to check for running instances, adopt state from prior initialization, acquire a process lock, and perform full initialization only when necessary. The global setup removes explicit app initialization, deferring this work to per-app beforeAll hooks that execute with a 5-minute timeout.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(e2e): lazy app init + playwright sharding for integration tests' directly and concisely summarizes the main changes: introducing lazy app initialization and Playwright sharding for integration tests.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}