Document considerations when using Vitest

README.md

@@ -3,17 +3,18 @@
 This package contains common utilities for testing UI components across
 Hypothesis frontend projects. It includes tools for:
 
- - Rendering UI components and unmounting them once the test ends
- - Waiting for conditions to be met
- - Mocking UI components
- - Testing accessibility using [axe-core](https://github.com/dequelabs/axe-core)
+- Rendering UI components and unmounting them once the test ends
+- Waiting for conditions to be met
+- Mocking UI components
+- Testing accessibility using [axe-core](https://github.com/dequelabs/axe-core)
 
 This package is designed to work with downstream projects that use Hypothesis's
 standard UI and UI testing stack, built on:
 
- - [Preact](https://preactjs.com)
- - [Enzyme](https://github.com/enzymejs/enzyme)
- - [babel-plugin-mockable-imports](https://github.com/robertknight/babel-plugin-mockable-imports)
+- [Preact](https://preactjs.com)
+- [Enzyme](https://github.com/enzymejs/enzyme)
+- [Vitest](http://vitest.dev/)
+- [babel-plugin-mockable-imports](https://github.com/robertknight/babel-plugin-mockable-imports)
 
 ## API guide
 
@@ -35,13 +36,13 @@ describe('MyWidget', () => {
   });
 
   it('should render', () => {
-    const wrapper = mount(<MyWidget/>);
+    const wrapper = mount(<MyWidget />);
 
     // Query component content etc.
   });
 
   it('should do something that requires component to be connected', () => {
-    const wrapper = mount(<MyWidget/>, { connected: true });
+    const wrapper = mount(<MyWidget />, { connected: true });
 
     // Test behavior that relies on rendered component being part of the
     // DOM tree under `document.body`.
@@ -51,9 +52,74 @@ describe('MyWidget', () => {
 
 ## Vitest
 
-This package has an optional peer dependency on `vitest`. Any vitest-specific
-utility is exposed in a separate `@hypothesis/frontend-testing/vitest` entry
-point.
+All projects depending on this package are expected to use Vitest to run tests.
+
+However, we don't follow all practices recommended by Vitest. You should take
+these points into consideration when reading Vitest's documentation:
+
+1. By default, Vitest uses [Vite](https://vite.dev/) to bundle the tests and
+   source code as test files are run.
+   Instead, we manually pre-bundle our tests and source code in a single file
+   with Rollup, and that's the only test file we run.
+   That file is still processed by Vite, but since it has nothing to transform,
+   the time it takes is negligible.
+2. Due to the point above, Vitest tries to capture and calculate code coverage while
+   tests and sources are bundled with Vite.
+   In our case, we use `babel-plugin-istanbul` to instrument the code coverage
+   while we do our own pre-bundling.
+   This requires two configuration options to be set in `babel-plugin-istanbul`,
+   so that `istanbul-lib-instrument` checks the file is already instrumented.
+   [See the discussion](https://github.com/vitest-dev/vitest/discussions/7841#discussioncomment-12855608).
+
+   ```js
+   [
+     'babel-plugin-istanbul',
+     {
+       coverageGlobalScope: 'globalThis',
+       coverageVariable: '__VITEST_COVERAGE__',
+
+       // Other options...
+     },
+   ];
+   ```
+
+### Istanbul coverage options
+
+As mentioned above, for the code coverage to be calculated properly, we need to
+use `babel-plugin-istanbul` and set these configuration options:
+
+```js
+{
+  coverageGlobalScope: 'globalThis',
+  coverageVariable: '__VITEST_COVERAGE__'
+}
+```
+
+This library provides these options for convenience, so that you don't need to
+define them everywhere.
+
+```js
+import { vitestCoverageOptions } from '@hypothesis/frontend-testing';
+import { babel } from '@rollup/plugin-babel';
+
+const babelRollupPlugin = babel({
+  // ...
+
+  presets: [
+    // ...
+  ],
+  plugins: [
+    [
+      'babel-plugin-istanbul',
+      {
+        ...vitestCoverageOptions,
+
+        // Other options...
+      },
+    ],
+  ],
+});
+```
 
 ### Summary reporter
 
@@ -66,8 +132,7 @@ still prints the real-time summary and details for any failed test.
 
 ```js
 // vitest.config.js
-
-import { SummaryReporter } from '@hypothesis/frontend-testing/vitest';
+import { SummaryReporter } from '@hypothesis/frontend-testing';
 import { defineConfig } from 'vitest/config';
 
 export default defineConfig({

package.json

@@ -33,11 +33,6 @@
   "peerDependencies": {
     "vitest": "^3.1.2"
   },
-  "peerDependenciesMeta": {
-    "vitest": {
-      "optional": true
-    }
-  },
   "files": [
     "lib/**/*.js",
     "lib/**/*.d.ts"

src/index.ts

@@ -3,5 +3,6 @@ export { checkAccessibility } from './accessibility.js';
 export { mockImportedComponents } from './mock-imported-components.js';
 export { mount, unmountAll } from './mount.js';
 export type { MountOptions } from './mount.js';
+export { SummaryReporter, vitestCoverageOptions } from './vitest.js';
 export type { TestTimeout, TimeoutSpec } from './wait.js';
 export { delay, waitFor, waitForElement } from './wait.js';

src/vitest.ts

@@ -10,3 +10,16 @@ export class SummaryReporter extends DefaultReporter {
     // Override this method to suppress individual file results
   }
 }
+
+/**
+ * These configuration options for `babel-plugin-istanbul` need to match the
+ * values set by Vitest internally, so that it picks the coverage
+ * instrumentation generated by said babel plugin instead of trying to generate
+ * its own.
+ *
+ * See https://github.com/vitest-dev/vitest/discussions/7841#discussioncomment-12855608
+ */
+export const vitestCoverageOptions = {
+  coverageGlobalScope: 'globalThis',
+  coverageVariable: '__VITEST_COVERAGE__',
+};

yarn.lock

@@ -299,9 +299,6 @@ __metadata:
     vitest: ^3.1.2
   peerDependencies:
     vitest: ^3.1.2
-  peerDependenciesMeta:
-    vitest:
-      optional: true
   languageName: unknown
   linkType: soft