From 4102905bde8dd7df3b64557d54ebe1cdae48ba3c Mon Sep 17 00:00:00 2001
From: Marcus Kohlberg <78424526+marcuskohlberg@users.noreply.github.com>
Date: Fri, 10 Jan 2025 15:06:49 +0100
Subject: [PATCH] update testing docs (#1698)

---
 docs/ts/develop/testing.md | 90 ++++++++++++++++++++++++++++----------
 1 file changed, 66 insertions(+), 24 deletions(-)

diff --git a/docs/ts/develop/testing.md b/docs/ts/develop/testing.md
index dcd3881eb5..b5eb87a2fe 100644
--- a/docs/ts/develop/testing.md
+++ b/docs/ts/develop/testing.md
@@ -6,46 +6,88 @@ subtitle: Confidence at speed
 lang: ts
 ---
 
-Encore provides a suite of built-in tooling to simplify testing your application.
+Encore provides built-in testing tools that make it simple to test your application using a variety of test runners.
 
-To run your tests, configure the `test` command in your `package.json` to the test runner of your choice,
-and then use `encore test` from the CLI. 
-The `encore test` command sets up all the necessary infrastructure in test mode before handing over to
-the test runner. 
+To run tests with Encore:
+
+1. Configure the `test` command in your `package.json` to use the test runner of your choice.
+2. Configure your test runner.
+3. Run `encore test` from the CLI.
+
+The `encore test` command automatically sets up all necessary infrastructure in test mode before running your tests.
 
 <GitHubLink 
     href="https://github.com/encoredev/examples/tree/main/ts/uptime" 
     desc="Uptime monitoring app with API endpoint unit tests written in Vitest." 
 />
 
-## Test Runners
+## Recommended Setup: Vitest
 
-We recommend using [Vitest](https://vitest.dev) as the test runner. It's very fast, has native support for
-ESM and TypeScript, and has a built-in compatibility layer for Jest's API.
+We recommend [Vitest](https://vitest.dev) as your test runner because it offers:
+- Fast execution
+- Native ESM and TypeScript support
+- Jest API compatibility
 
-## Integration testing
+### Setting up Vitest
 
-Since Encore removes almost all boilerplate, most of the code you write
-is business logic that involves databases and calling APIs between services.
-Such behavior is most easily tested with integration tests.
+1. Create `vite.config.json` in your application's root directory:
 
-When running tests, Encore automatically sets up the databases you need
-in a separate database cluster. They are additionally configured to skip `fsync`
-and to use an in-memory filesystem since durability is not a concern for automated tests.
+```ts
+/// <reference types="vitest" />
+import { defineConfig } from "vite";
+import path from "path";
 
-This drastically reduces the speed overhead of writing integration tests.
+export default defineConfig({
+  resolve: {
+    alias: {
+      "~encore": path.resolve(__dirname, "./encore.gen"),
+    },
+  },
+});
+```
 
-In general, Encore applications tend to focus more on integration tests
-compared to traditional applications that are heavier on unit tests.
-This is nothing to worry about and is the recommended best practice.
+2. Update your `package.json` to include:
 
-## Testing from your IDE
+```json
+{
+  "scripts": {
+    "test": "vitest"
+  }
+}
+```
 
-### Visual Studio Code (VS Code)
+You're done! Now you can run your tests with `encore test`.
 
-If you're using Vitest, install the official Vitest VS Code extension and then add to the `.vscode/settings.json` file:
+### Optional: IDE Integration
 
+#### VS Code Setup
+
+If using Vitest, follow these steps:
+1. Install the official Vitest VS Code extension
+2. Add to `.vscode/settings.json`:
+
+```json
+{
+  "vitest.commandLine": "encore test"
+}
 ```
-"vitest.commandLine": "encore test"
-```
+
+## 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
+
+These optimizations make integration tests nearly as fast as unit tests.