Test Database Configuration#

Cedar's test infrastructure handles three interconnected concerns: routing the cedar test command to the right test runner (Jest or Vitest), setting up the DATABASE_URL for API tests, and synchronizing the Prisma schema against a test database before tests run. Both Jest and Vitest paths share the same environment variable conventions and Prisma sync logic.

CLI Routing: Jest vs. Vitest#

The top-level cedar test command is registered in packages/cli/src/index.ts using a runtime check:

projectIsEsm() ? testCommandEsm : testCommand

• Non-ESM projects load commands/test.ts, which delegates to testHandler.ts — the Jest path.
• ESM projects load commands/testEsm.ts, which delegates to testHandlerEsm.ts — the Vitest path.

Both command files expose --db-push (default true) and --force 12. The Jest command additionally exposes --watch and --collect-coverage 3.

Database URL Resolution#

Both handlers resolve DATABASE_URL with the same fallback chain 45:

1. Use TEST_DATABASE_URL if set.
2. Otherwise, default to a SQLite file at {generated.base}/test.db — e.g. .cedar/test.db.

The resolved value is injected into the child process environment when Jest/Vitest is spawned 67.

If --db-push false is passed and the api side is included, the handler sets SKIP_DB_PUSH=1 to skip schema synchronization entirely 89.

Prisma Schema Synchronization#

Schema sync runs once before tests begin. The implementation is duplicated across two entry points that share the same core reset functionality:

• Jest: packages/testing/src/config/jest/api/globalSetup.ts — runs as Jest's globalSetup.
• Vitest: packages/testing/src/api/vitest/CedarApiVitestEnv.ts — runs inside the custom cedar-api Vitest environment's setup() hook.

The Vitest implementation captures stdout and stderr to provide detailed error diagnostics when the database reset fails, whereas the Jest implementation uses inherited stdio. This improves the developer experience in Vitest by showing Prisma's actual error messages when reset operations fail.

Both entry points:

1. Check SKIP_DB_PUSH=1 and bail early if set 1011.
2. Set DATABASE_URL to TEST_DATABASE_URL or the SQLite fallback 1213.
3. Choose a Prisma command based on TEST_DATABASE_STRATEGY 1415:
   • TEST_DATABASE_STRATEGY=reset → prisma migrate reset --force
   • (default) → prisma db push --force-reset --accept-data-loss
4. Run the command synchronously via execa.sync, adjusting the executor for pnpm vs. npx 1617.

Vitest API Environment (cedar-api)#

The Vitest path uses a custom environment named cedar-api 18, wired up by the cedarVitestApiConfigPlugin. The plugin sets:

• test.environment → path to CedarApiVitestEnv.js 19
• test.fileParallelism: false — because all API tests share a single database and cannot run concurrently 20
• test.setupFiles → vitest-api.setup.js 21

Note: The poolOptions.forks.singleFork workaround used in Vitest 3 was replaced by fileParallelism: false when Vitest 4 dropped poolOptions 22.

For Jest, the equivalent serial execution is enforced by the jest-serial-runner in the API Jest preset 23.

Safety: Non-Standard Datasource URLs#

When the api side is included, both handlers call warnIfNonStandardDatasourceUrl before running tests. If Prisma is configured with an environment variable other than DATABASE_URL, Cedar warns that it will not override it — which could direct destructive reset commands at a production database. The --force flag bypasses the interactive prompt.

Environment Variables Reference#

Key Source Files#