GITBOOK-50: update Clarinet Vitest config

Author: eric-stacks

docs/build/clarinet/project-structure.md

@@ -116,23 +116,36 @@ The **package.json** defines your testing environment and dependencies:
 
 ### Vitest configuration
 
-The **vitest.config.js** configures the testing framework:
-
-```js
-
-/// <reference types="vitest" />
-
-import { defineConfig } from "vite";
-import { vitestSetupFilePath, getClarinetVitestsArgv } from "@stacks/clarinet-sdk/vitest";
+The **`vitest.config.ts`** (or `.js`) configures the testing framework. Make sure to import `defineConfig` from `vitest/config` (and not for `vite`). This configuration will work with Vitest v4 and higher.
+
+{% code expandable="true" %}
+```typescript
+import { defineConfig } from "vitest/config";
+import {
+  vitestSetupFilePath,
+  getClarinetVitestsArgv,
+} from "@stacks/clarinet-sdk/vitest";
+
+/*
+  In this file, Vitest is configured so that it works seamlessly with Clarinet and the Simnet.
+  The `vitest-environment-clarinet` will initialise the clarinet-sdk
+  and make the `simnet` object available globally in the test files.
+  `vitestSetupFilePath` points to a file in the `@stacks/clarinet-sdk` package that does two things:
+    - run `before` hooks to initialize the simnet and `after` hooks to collect costs and coverage reports.
+    - load custom vitest matchers to work with Clarity values (such as `expect(...).toBeUint()`)
+  The `getClarinetVitestsArgv()` will parse options passed to the command `vitest run --`
+    - vitest run -- --manifest ./Clarinet.toml  # pass a custom path
+    - vitest run -- --coverage --costs          # collect coverage and cost reports
+*/
 
 export default defineConfig({
   test: {
-    environment: "clarinet", // use vitest-environment-clarinet
+    // use vitest-environment-clarinet
+    environment: "clarinet",
     pool: "forks",
-    poolOptions: {
-      threads: { singleThread: true },
-      forks: { singleFork: true },
-    },
+    // clarinet handles test isolation by resetting the simnet between tests
+    isolate: false,
+    maxWorkers: 1,
     setupFiles: [
       vitestSetupFilePath,
       // custom setup files can be added here
@@ -146,6 +159,7 @@ export default defineConfig({
   },
 });
 ```
+{% endcode %}
 
 This configuration enables:
 
@@ -154,10 +168,58 @@ This configuration enables:
 * **Coverage tracking**: Generate reports in multiple formats
 * **Custom setup**: Add project-specific test utilities
 
+<details>
+
+<summary>For Vitest v3 and earlier, use the configuration below.</summary>
+
+```typescript
+import { defineConfig } from "vitest/config";
+import {
+  vitestSetupFilePath,
+  getClarinetVitestsArgv,
+} from "@stacks/clarinet-sdk/vitest";
+
+/*
+  In this file, Vitest is configured so that it works seamlessly with Clarinet and the Simnet.
+  The `vitest-environment-clarinet` will initialise the clarinet-sdk
+  and make the `simnet` object available globally in the test files.
+  `vitestSetupFilePath` points to a file in the `@hirosystems/clarinet-sdk` package that does two things:
+    - run `before` hooks to initialize the simnet and `after` hooks to collect costs and coverage reports.
+    - load custom vitest matchers to work with Clarity values (such as `expect(...).toBeUint()`)
+  The `getClarinetVitestsArgv()` will parse options passed to the command `vitest run --`
+    - vitest run -- --manifest ./Clarinet.toml  # pass a custom path
+    - vitest run -- --coverage --costs          # collect coverage and cost reports
+*/
+
+export default defineConfig({
+  test: {
+    // use vitest-environment-clarinet
+    environment: "clarinet",
+    pool: "forks",
+    poolOptions: {
+      forks: { singleFork: true },
+    },
+    setupFiles: [
+      vitestSetupFilePath,
+      // custom setup files can be added here
+    ],
+    environmentOptions: {
+      clarinet: {
+        ...getClarinetVitestsArgv(),
+        // add or override options
+      },
+    },
+  },
+});
+```
+
+</details>
+
 ### TypeScript configuration
 
 The **tsconfig.json** provides TypeScript support:
 
+{% code expandable="true" %}
 ```json
 {
   "compilerOptions": {
@@ -185,6 +247,7 @@ The **tsconfig.json** provides TypeScript support:
   ]
 }
 ```
+{% endcode %}
 
 Properly setting the `include` property ensures TypeScript picks up the helpers defined in the Clarinet SDK package along with your tests.