Automated testing
Confidence at speed
Encore provides built-in testing tools that make it simple to test your application using a variety of test runners.
To run tests with Encore:
- Configure the
test
command in yourpackage.json
to use the test runner of your choice. - Configure your test runner.
- Run
encore test
from the CLI.
The encore test
command automatically sets up all necessary infrastructure in test mode before running your tests.
Related example
$ encore app create --example=ts/uptime
Recommended Setup: Vitest
We recommend Vitest as your test runner because it offers:
- Fast execution
- Native ESM and TypeScript support
- Jest API compatibility
Setting up Vitest
- Create
vite.config.ts
in your application's root directory:
/// <reference types="vitest" />
import { defineConfig } from "vite";
import path from "path";
export default defineConfig({
resolve: {
alias: {
"~encore": path.resolve(__dirname, "./encore.gen"),
},
},
});
- Update your
package.json
to include:
{
"scripts": {
"test": "vitest"
}
}
You're done! Now you can run your tests with encore test
.
Optional: IDE Integration
VS Code Setup
If using Vitest, follow these steps:
- Install the official Vitest VS Code extension
- Add to
.vscode/settings.json
:
{
"vitest.commandLine": "encore test"
}
As of Vitest plugin version 0.5 (issue), environment configuration requires an updated approach. The following configuration is required to ensure proper functionality:
Update settings.json
to include:
"vitest.nodeEnv": {
// generated with `encore daemon env | grep ENCORE_RUNTIME_LIB | cut -d'=' -f2`
"ENCORE_RUNTIME_LIB": "/opt/homebrew/Cellar/encore/1.44.5/libexec/runtimes/js/encore-runtime.node"
}
When running tests within VSCode, file-level parallel execution must be disabled. Update your vite.config.ts
as follows:
// File vite.config.ts
export default defineConfig({
resolve: {
alias: {
"~encore": path.resolve(__dirname, "./encore.gen"),
},
},
test: {
fileParallelism: false,
},
});
To improve the performance in CI, you can re-enable the parallel execution by overwriting the config in cli encore test --fileParallelism=true
.
Integration Testing Best Practices
Encore applications typically focus on integration tests rather than unit tests because:
- Encore eliminates most boilerplate code
- Your code primarily consists of business logic involving databases and inter-service API calls
- Integration tests better verify this type of functionality
Test Environment Benefits
When running tests, Encore automatically:
- Sets up separate test databases
- Configures databases for optimal test performance by:
- Skipping
fsync
- Using in-memory filesystems
- Removing durability overhead
- Skipping
These optimizations make integration tests nearly as fast as unit tests.