feat: prepare the Vitest API to be stable #6962

sheremet-va · 2024-11-25T17:26:59Z

Description

Goals of this PR:

Reduce the size of core.ts
Deprecate APIs that we exposed, and mark internal APIs with @internal to remove them from types
Document all relevant Node.js APIs

The new API without deprecated methods:

declare class Vitest {
    readonly mode: VitestRunMode;
    readonly version: string;
    readonly logger: Logger;
    readonly packageInstaller: VitestPackageInstaller;
    readonly distPath: string;
    readonly watcher: VitestWatcher
    readonly state: StateManager; /** marked experimental */
    readonly snapshot: SnapshotManager;
    readonly cache: VitestCache;
    readonly config: ResolvedConfig;
    readonly vite: ViteDevServer;
    projects: TestProject[];
    
    provide: <T extends keyof ProvidedContext & string>(key: T, value: ProvidedContext[T]) => void;
    getProvidedContext(): ProvidedContext
    getRootProject(): TestProject;
    getProjectByName(name: string): TestProject;
    
    mergeReports(): Promise<TestRunResult>;
    collect(filters?: string[]): Promise<TestRunResult>;
    start(filters?: string[]): Promise<TestRunResult>;
    init(): Promise<void>;

    listFiles(filters?: string[]): Promise<TestSpecification[]>;
    getModuleSpecifications(moduleId: string): TestSpecification[];
    globTestSpecifications(filters?: string[]): Promise<TestSpecification[]>;
    
    runTestSpecifications(specifications: TestSpecification[], allTestsRun?: boolean): Promise<TestRunResult>;
    // difference is that `rerun` triggers `onWatcher*` events
    rerunTestSpecifications(specifications: TestSpecification[], allTestsRun?: boolean): Promise<TestRunResult>;
    collectTests(specifications: TestSpecification[]): Promise<TestRunResult>;
    
    cancelCurrentRun(reason: CancelReason): Promise<void>;
    invalidateFile(filepath: string): void;
    shouldKeepServer(): boolean;
    
    enableSnapshotUpdate(): void
    resetSnapshotUpdate(): void
    setGlobalTestNamePattern(pattern: string | RegExp): void
    resetGlobalTestNamePattern(): void
    
    import<T>(moduleId: string): Promise<T>
    
    onServerRestart(fn: OnServerRestartHandler): void;
    onCancel(fn: (reason: CancelReason) => Awaitable<void>): void;
    onClose(fn: () => Awaitable<void>): void;
    onTestsRerun(fn: OnTestsRerunHandler): void;
    onFilterWatchedSpecification(fn: (spec: TestSpecification) => boolean): void;
    
    close(): Promise<void>;
    exit(force?: boolean): Promise<void>;
}

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

It's really useful if your PR references an issue where it is discussed ahead of time. If the feature is substantial or introduces breaking changes without a discussion, PR might be closed.
Ideally, include a test that fails without this PR but passes with it.
Please, don't make changes to pnpm-lock.yaml unless you introduce a new test example.

Tests

Run the tests with pnpm test:ci.

Documentation

If you introduce new functionality, document it. You can run documentation with pnpm run docs command.

Changesets

Changes in changelog are generated from PR name. Please, make sure that it explains your changes in an understandable manner. Please, prefix changeset messages with feat:, fix:, perf:, docs:, or chore:.

netlify · 2024-11-25T17:31:30Z

✅ Deploy Preview for vitest-dev ready!

Name	Link
🔨 Latest commit	`2ad4d6f`
🔍 Latest deploy log	https://app.netlify.com/sites/vitest-dev/deploys/675814110cbabb0008af527b
😎 Deploy Preview	https://deploy-preview-6962--vitest-dev.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

docs/advanced/api/index.md

packages/vitest/src/node/core.ts

packages/vitest/src/node/watcher.ts

docs/advanced/api/index.md

docs/advanced/api/vitest.md

docs/advanced/api/test-project.md

docs/advanced/api/vitest.md

@Lordfirespeed

##### [v3.0.0](https://github.com/vitest-dev/vitest/releases/tag/v3.0.0) ##### 🚨 Breaking Changes - `spy.mockReset` changes - by [@Lordfirespeed](https://github.com/Lordfirespeed) in vitest-dev/vitest#6426 [<samp>(db7a8)</samp>](vitest-dev/vitest@db7a8888) - Pass down context to test hooks - by [@sheremet-va](https://github.com/sheremet-va) in vitest-dev/vitest#7034 [<samp>(82c2e)</samp>](vitest-dev/vitest@82c2e244) - Support Vite 6 - by [@sheremet-va](https://github.com/sheremet-va) in vitest-dev/vitest#7026 [<samp>(7abe8)</samp>](vitest-dev/vitest@7abe854c) - **coverage**: Always exclude test files - by [@AriPerkkio](https://github.com/AriPerkkio) in vitest-dev/vitest#7254 [<samp>(b5268)</samp>](vitest-dev/vitest@b5268965) - **deps**: Update fake-timers to v14.0.0 - by [@xxzefgh](https://github.com/xxzefgh) and [@hi-ogawa](https://github.com/hi-ogawa) in vitest-dev/vitest#7097 [<samp>(c98b4)</samp>](vitest-dev/vitest@c98b4b1c) - **expect**: Check more properties for error equality - by [@hi-ogawa](https://github.com/hi-ogawa) and [@sheremet-va](https://github.com/sheremet-va) in vitest-dev/vitest#5876 [<samp>(10023)</samp>](vitest-dev/vitest@100230e9) - **runner**: Support `describe(..., { shuffle: boolean })` and inherit from parent suite - by [@hi-ogawa](https://github.com/hi-ogawa) in vitest-dev/vitest#6670 [<samp>(aa1da)</samp>](vitest-dev/vitest@aa1dac3d) - **snapshot**: Reset snapshot state for `retry` and `repeats` - by [@hi-ogawa](https://github.com/hi-ogawa) in vitest-dev/vitest#6817 [<samp>(e8ce9)</samp>](vitest-dev/vitest@e8ce94cf) - **spy**: SpyOn reuses mock if method is already spyed on - by [@sheremet-va](https://github.com/sheremet-va) and [@hi-ogawa](https://github.com/hi-ogawa) in vitest-dev/vitest#6464 [<samp>(b3e43)</samp>](vitest-dev/vitest@b3e43d04) - **vitest**: Don't expose default toFake config - by [@sheremet-va](https://github.com/sheremet-va) in vitest-dev/vitest#6288 [<samp>(e3144)</samp>](vitest-dev/vitest@e3144fd8) ##### 🚀 Features - Support inline `diff` options and support `printBasicPrototype` - by [@hi-ogawa](https://github.com/hi-ogawa), [@sheremet-va](https://github.com/sheremet-va) and **Michał Grzegorzewski** in vitest-dev/vitest#6740 [<samp>(39186)</samp>](vitest-dev/vitest@391860f7) - Allow a custom note when calling `ctx.skip()` dynamically - by [@sheremet-va](https://github.com/sheremet-va) in vitest-dev/vitest#6805 [<samp>(697c3)</samp>](vitest-dev/vitest@697c35c5) - Allow inline workspace configuration - by [@sheremet-va](https://github.com/sheremet-va) in vitest-dev/vitest#6923 [<samp>(562e1)</samp>](vitest-dev/vitest@562e1b14) - Provide the current project to the global setup - by [@sheremet-va](https://github.com/sheremet-va) in vitest-dev/vitest#6942 [<samp>(a5bbc)</samp>](vitest-dev/vitest@a5bbc0a9) - Print project name as a label - by [@sheremet-va](https://github.com/sheremet-va) in vitest-dev/vitest#6925 [<samp>(a3bef)</samp>](vitest-dev/vitest@a3bef598) - Print a deprecation warning if suite or test uses object as the third argument - by [@sheremet-va](https://github.com/sheremet-va) in vitest-dev/vitest#7031 [<samp>(407f1)</samp>](vitest-dev/vitest@407f10e4) - Expose versions from `vitest/node` entry point and statically on Vitest - by [@sheremet-va](https://github.com/sheremet-va) in vitest-dev/vitest#7029 [<samp>(be8d4)</samp>](vitest-dev/vitest@be8d479b) - `diff.printBasicPrototype: false` by default - by [@hi-ogawa](https://github.com/hi-ogawa) in vitest-dev/vitest#7043 [<samp>(2b5c5)</samp>](vitest-dev/vitest@2b5c5201) - Prepare the Vitest API to be stable - by [@sheremet-va](https://github.com/sheremet-va) in vitest-dev/vitest#6962 [<samp>(9a1b5)</samp>](vitest-dev/vitest@9a1b5012) - Support Vite v6 in mocker package - by [@cexbrayat](https://github.com/cexbrayat) in vitest-dev/vitest#7058 [<samp>(96f47)</samp>](vitest-dev/vitest@96f47d37) - Allow multi-browser configuration - by [@sheremet-va](https://github.com/sheremet-va) in vitest-dev/vitest#6975 [<samp>(78b62)</samp>](vitest-dev/vitest@78b62ffe) - Add resolved project names to the reporter API - by [@userquin](https://github.com/userquin) in vitest-dev/vitest#7213 [<samp>(91758)</samp>](vitest-dev/vitest@91758360) - Introduce the new reporter API - by [@sheremet-va](https://github.com/sheremet-va) and [@AriPerkkio](https://github.com/AriPerkkio) in vitest-dev/vitest#7069 [<samp>(76662)</samp>](vitest-dev/vitest@766624ab) - Add `describe.for` - by [@hi-ogawa](https://github.com/hi-ogawa) in vitest-dev/vitest#7253 [<samp>(0ad28)</samp>](vitest-dev/vitest@0ad2860b) - **api**: - Add onBrowserInit event - by [@sheremet-va](https://github.com/sheremet-va) in vitest-dev/vitest#7255 [<samp>(80ce0)</samp>](vitest-dev/vitest@80ce0e1c) - **browser**: - Support `actionTimeout` as playwright provider options - by [@hi-ogawa](https://github.com/hi-ogawa) in vitest-dev/vitest#6984 [<samp>(e2c29)</samp>](vitest-dev/vitest@e2c29eaf) - Support clipboard api `userEvent.copy, cut, paste` - by [@hi-ogawa](https://github.com/hi-ogawa) in vitest-dev/vitest#6769 [<samp>(843a6)</samp>](vitest-dev/vitest@843a621e) - Implement locator.nth() - by [@xeger](https://github.com/xeger) and [@sheremet-va](https://github.com/sheremet-va) in vitest-dev/vitest#7137 [<samp>(38458)</samp>](vitest-dev/vitest@38458ea6) - **cli**: - Support excluding projects with `--project=!pattern` - by [@haines](https://github.com/haines) in vitest-dev/vitest#6924 [<samp>(ebfe9)</samp>](vitest-dev/vitest@ebfe942c) - Support specifying a line number when filtering tests - by [@mzhubail](https://github.com/mzhubail) and [@sheremet-va](https://github.com/sheremet-va) in vitest-dev/vitest#6411 [<samp>(4d94b)</samp>](vitest-dev/vitest@4d94b956) - Support location filters for suites - by [@mzhubail](https://github.com/mzhubail) in vitest-dev/vitest#7048 [<samp>(751e2)</samp>](vitest-dev/vitest@751e2dce) - **coverage**: - `thresholds` to support maximum uncovered items - by [@jonahkagan](https://github.com/jonahkagan) in vitest-dev/vitest#7061 [<samp>(bde98)</samp>](vitest-dev/vitest@bde98b6d) - **expect**: - Add `toHaveBeenCalledExactlyOnceWith` expect matcher - by [@jacoberdman2147](https://github.com/jacoberdman2147) and [@sheremet-va](https://github.com/sheremet-va) in vitest-dev/vitest#6894 [<samp>(ff662)</samp>](vitest-dev/vitest@ff66206a) - Add `toHaveBeenCalledAfter` and `toHaveBeenCalledBefore` utility - by [@Barbapapazes](https://github.com/Barbapapazes) and [@sheremet-va](https://github.com/sheremet-va) in vitest-dev/vitest#6056 [<samp>(85e6f)</samp>](vitest-dev/vitest@85e6f99f) - Add `toSatisfy` asymmetric matcher - by [@hi-ogawa](https://github.com/hi-ogawa) in vitest-dev/vitest#7022 [<samp>(f691a)</samp>](vitest-dev/vitest@f691ad76) - Add `toBeOneOf` matcher - by [@zirkelc](https://github.com/zirkelc) and [@hi-ogawa](https://github.com/hi-ogawa) in vitest-dev/vitest#6974 [<samp>(3d742)</samp>](vitest-dev/vitest@3d742b2b) - **reporter**: - Add support for function type to classname option in the junit reporter - by [@jpleclerc](https://github.com/jpleclerc), **Jean-Philippe Leclerc** and [@hi-ogawa](https://github.com/hi-ogawa) in vitest-dev/vitest#6839 [<samp>(dc238)</samp>](vitest-dev/vitest@dc238e92) - **reporters**: - `summary` option for `verbose` and `default` reporters - by [@AriPerkkio](https://github.com/AriPerkkio) in vitest-dev/vitest#6893 [<samp>(511b7)</samp>](vitest-dev/vitest@511b73c7) - **runner**: - Test context can inject values from the config's `provide` - by [@sheremet-va](https://github.com/sheremet-va) in vitest-dev/vitest#6813 [<samp>(85c64)</samp>](vitest-dev/vitest@85c64e35) - Add "queued" state - by [@sheremet-va](https://github.com/sheremet-va) and [@AriPerkkio](https://github.com/AriPerkkio) in vitest-dev/vitest#6931 [<samp>(5f8d2)</samp>](vitest-dev/vitest@5f8d2091) - **snapshot**: - Provide `config` to `resolveSnapshotPath` - by [@hi-ogawa](https://github.com/hi-ogawa) in vitest-dev/vitest#6800 [<samp>(746d8)</samp>](vitest-dev/vitest@746d8986) - **ui**: - Allow run individual tests/suites from the UI - by [@userquin](https://github.com/userquin) in vitest-dev/vitest#6641 [<samp>(d9cc8)</samp>](vitest-dev/vitest@d9cc81dd) - Make clicking on a test in the UI open the report section and scroll to the test failure if applicable - by [@jacoberdman2147](https://github.com/jacoberdman2147) in vitest-dev/vitest#6900 [<samp>(1bf27)</samp>](vitest-dev/vitest@1bf27f0d) - Allow hide/show node_modules in module graph tab - by [@userquin](https://github.com/userquin) in vitest-dev/vitest#7217 [<samp>(50cf6)</samp>](vitest-dev/vitest@50cf61b8) - **vitest**: - Include `coverageMap` in json report - by [@sheremet-va](https://github.com/sheremet-va) in vitest-dev/vitest#6606 [<samp>(9c8f7)</samp>](vitest-dev/vitest@9c8f7e3e) - Add `onTestsRerun` method to global setup context - by [@sheremet-va](https://github.com/sheremet-va) in vitest-dev/vitest#6803 [<samp>(e26e0)</samp>](vitest-dev/vitest@e26e066c) ##### 🐞 Bug Fixes - Misc fix for vite 6 ecosystem ci - by [@hi-ogawa](https://github.com/hi-ogawa) in vitest-dev/vitest#6867 [<samp>(80f8b)</samp>](vitest-dev/vitest@80f8bbf4) - Respect `cacheDir` when optimizer is enabled - by [@hi-ogawa](https://github.com/hi-ogawa) in vitest-dev/vitest#6910 [<samp>(0b08b)</samp>](vitest-dev/vitest@0b08bc11) - Reset runningPromise after `finally` in case there is an error to avoid it getting stuck - by [

sheremet-va mentioned this pull request Dec 1, 2024

refactor: proposal for the public Vitest API #6405

Closed

sheremet-va force-pushed the refactor/vitest-prepare-stable branch 2 times, most recently from d267bf6 to 2d421a5 Compare December 2, 2024 16:38

sheremet-va modified the milestones: 2.2.0, 3.0.0 Dec 3, 2024

sheremet-va force-pushed the refactor/vitest-prepare-stable branch 2 times, most recently from 483acc6 to 78d0af9 Compare December 6, 2024 08:58

sheremet-va marked this pull request as ready for review December 6, 2024 17:15

AriPerkkio reviewed Dec 9, 2024

View reviewed changes

docs/advanced/api/vitest.md Show resolved Hide resolved

sheremet-va added 18 commits December 10, 2024 10:46

feat: prepare the Vitest API to be stable

dd4f623

chore: cleanup

250c4e4

chore: add more type annotations, move globbing into a separate class

a455c94

chore: cleanup

7f48a4b

feat: hide the task in reported tasks

414c965

chore: fix types in tests

de9e6e3

fix: fullName has file

8749add

refactor: remove the usage of getProjectByTaskId

b8830fb

refactor: move watcher functions into a separate class

32e0a95

chore: cleanup

2e2e701

chore: get root

e46b2b0

chore: add ready() method

3b2c25f

chore: use fullName

59dc0e7

fix: correctly print errors

4d414c8

chore: ignore typecheck error

4647988

chore: make the rest into getters with a check

fa62000

fix: add a separate tsconfig for failing tests

8a9f47c

refactor: add onFilterWatchedSpecification and getProvidedContext

0931b3c

sheremet-va added 21 commits December 10, 2024 10:48

refactor: deprecate ExtendedContext

da7e999

refactor: remove deprecated APIs from custom-pool

e2598cc

refactor: remove deprecated APIs from sequencers

1eaa705

docs: update pool docs

47e5484

refactor: remove ready API

6c4030a

refactor: resolve workspace before reporters

e9cf357

feat: expose resolveConfig

693b23f

docs: document resolveConfig

af73c51

docs: document WorkspaceSpec type migration

e09c25c

test: fix CI test fail

104b80f

fix: throw if --project doesn't exist, cleanup

19fd6f2

docs: finish docs

a6c17a6

chore: automatically mark the test file as cached

de8fa28

docs: add an example with watcher to guide

90dad97

chore: review

eed0e46

docs: expose the selector string

f8a6e9b

docs: locator's selector

491fc3c

feat: unwrap locator into a string

92f0f15

docs: fix import

085bf5b

docs: remove old start method

c5cbaa0

chore: fix deps

c9e14c2

sheremet-va force-pushed the refactor/vitest-prepare-stable branch from 9c5cc3d to c9e14c2 Compare December 10, 2024 09:48

chore: lint

23602f0

AriPerkkio previously approved these changes Dec 10, 2024

View reviewed changes

docs: correction

2ad4d6f

sheremet-va dismissed AriPerkkio’s stale review via 2ad4d6f December 10, 2024 10:12

sheremet-va merged commit 9a1b501 into vitest-dev:main Dec 10, 2024
3 checks passed

sheremet-va deleted the refactor/vitest-prepare-stable branch December 10, 2024 10:12

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

feat: prepare the Vitest API to be stable #6962

feat: prepare the Vitest API to be stable #6962

Uh oh!

sheremet-va commented Nov 25, 2024 •

edited

Loading

Uh oh!

netlify bot commented Nov 25, 2024 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

feat: prepare the Vitest API to be stable #6962

feat: prepare the Vitest API to be stable #6962

Uh oh!

Conversation

sheremet-va commented Nov 25, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

Tests

Documentation

Changesets

Uh oh!

netlify bot commented Nov 25, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for vitest-dev ready!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sheremet-va commented Nov 25, 2024 •

edited

Loading

netlify bot commented Nov 25, 2024 •

edited

Loading