/** * vapor-chamber/vitest - the testing entry, with its side effects. * * Load it as a setup file and every test file gets, with no import of its own: * * - the matchers, registered with `expect.extend`; * - a fresh, tapped shared bus before each test: `getCommandBus()` returns a * real `createCommandBus()` bus that `tap()` records, so what `useCommand()` * and islands dispatch can be asserted directly. * - and a failed test, on any assertion, shows the dispatches it made on tapped * buses, listed the way Vitest lists a spy's calls. * * The same module's types augment Vitest's `Matchers`, so one `types` entry * gives both. Everything else is `vapor-chamber/vitest/pure`, re-exported. * * THE LIBRARY IS IMPORTED LAZILY, inside beforeEach, never at load. The * one-shot Vue detection and the warn-once state in chamber.ts assume nothing * imported the library before a test set its preconditions. Measured on this * repository's suite: in the full run, importing at load fails 4 tests in 2 files and importing * inside beforeEach fails none; with each file run alone, both fail the same * 4, because the async detection then lands before those tests. Those two * files assert detection from a clean start, and `vaporChamberTest()`'s * `sharedBus.exclude` is how a suite like that opts out. * It is imported by its own package name, so the setup file and the tests * share one module instance (measured in five configurations, C.4), and the * build keeps the specifier external instead of bundling a second copy. * * THE BUS IS REPLACED BEFORE EACH TEST, not reset after it, so a failed test's * bus and what it recorded are still there to inspect afterwards. * * @example * // vitest.config.ts * export default defineConfig({ test: { setupFiles: ['vapor-chamber/vitest'] } }); * * // tsconfig.json * { "compilerOptions": { "types": ["vapor-chamber/vitest"] } } * * // a test * it('clicking Add dispatches cartAdd', () => { * clickAdd(); * expect(getCommandBus()).toHaveBeenDispatchedWith('cartAdd', { qty: 1 }); * }); */ import { expect, type TestAPI } from 'vitest'; import type { AsyncCommandBus, CommandBus } from './command-bus'; import { type VaporChamberMatchers } from './vitest-pure'; export * from './vitest-pure'; /** * Vitest's own `test`, extended with two fixtures through `test.extend`, the * way Vitest defines reusable setup. Vitest's `test` is not changed; this is * the new API `extend` returns. * * - `bus`: a tapped `createCommandBus()`, the setup a bus test most often opens with. * - `asyncBus`: a tapped `createAsyncCommandBus()`. * * Both are lazy, as every Vitest fixture is: a test that does not destructure * one builds nothing, and the library is imported inside the fixture, for the * same reason beforeEach imports it there (see the header). * * `bus` IS NOT THE SHARED BUS. It is a bus of its own, like the * `createCommandBus()` it replaces, so a test using it is isolated from what * `useCommand()` and islands reach through `getCommandBus()`, which stays the * tapped shared bus installed before each test. A test that wants the shared * bus reads `getCommandBus()`, or defines that fixture with `.extend`. * * Neither is disposed after the test, as the shared bus is not: a failed * test's bus and its record stay as they were, and a bus the test no longer * references is collected with its record. * * After `vi.resetModules()` the fixture imports a fresh module instance, as * beforeEach does, while the file's static imports keep the first one. A test * that mixes the two (`instanceof BusError`, a plugin with module state such * as `history`) creates its bus from its own import instead. * * Build your own on top with `.extend`, from any file: * * @example * import { expect, it } from 'vapor-chamber/vitest'; * * export const shopTest = it.extend('shop', ({ bus }) => { * registerShop(bus); * return bus; * }); * * shopTest('adding to the cart', ({ shop }) => { * shop.dispatch('cartAdd', { id: 1 }, { qty: 1 }); * expect(shop).toHaveBeenDispatchedWith('cartAdd', { qty: 1 }); * }); */ export declare const test: TestAPI>; /** The fixtures `test` and `it` add to Vitest's test context. */ export interface VaporChamberFixtures { /** A tapped `createCommandBus()`, new in each test that destructures it. Not the shared bus. */ bus: CommandBus; /** A tapped `createAsyncCommandBus()`, new in each test that destructures it. */ asyncBus: AsyncCommandBus; } /** * Fixtures `F` in the shape Vitest 5's builder records for test-scoped * fixtures (its AddBuilderTest): the `$__` keys are how a later `.extend` * knows which scope each fixture belongs to. Named here so the declaration * reads `TestAPI>`; left to inference it * printed two nested `Omit`s, and `TestAPI` alone is not * assignable from what `.extend` returns. */ type TestScoped = F & { readonly $__worker?: object; readonly $__file?: object; readonly $__test?: F; }; /** The same API as `test`, as Vitest's `it` is its `test`. */ export declare const it: TestAPI>; /** Vitest's own `expect`, with the matchers registered, so one import serves a test file. */ export { expect }; declare module 'vitest' { interface Matchers extends VaporChamberMatchers { } } //# sourceMappingURL=vitest.d.ts.map