diff --git a/docs/config/index.md b/docs/config/index.md index f8c9624455b8..a89a383bf959 100644 --- a/docs/config/index.md +++ b/docs/config/index.md @@ -1711,17 +1711,11 @@ export default defineConfig({ ``` ::: tip -To have a better type safety when using built-in providers, you can add one of these types (for provider that you are using) to your tsconfig's `compilerOptions.types` field: +To have a better type safety when using built-in providers, you should reference one of these types (for provider that you are using) in your [config file](/config/file): -```json -{ - "compilerOptions": { - "types": [ - "@vitest/browser/providers/webdriverio", - "@vitest/browser/providers/playwright" - ] - } -} +```ts +/// +/// ``` ::: diff --git a/docs/guide/browser/assertion-api.md b/docs/guide/browser/assertion-api.md index e7cb87845a0e..c768cc10c1d8 100644 --- a/docs/guide/browser/assertion-api.md +++ b/docs/guide/browser/assertion-api.md @@ -32,35 +32,17 @@ Vitest bundles the [`@testing-library/jest-dom`](https://github.com/testing-libr - [`toHaveRole`](https://github.com/testing-library/jest-dom#toHaveRole) - [`toHaveErrorMessage`](https://github.com/testing-library/jest-dom#toHaveErrorMessage) -If you are using TypeScript or want to have correct type hints in `expect`, make sure you have either `@vitest/browser/providers/playwright` or `@vitest/browser/providers/webdriverio` specified in your `tsconfig` depending on the provider you use. If you use the default `preview` provider, you can specify `@vitest/browser/matchers` instead. +If you are using [TypeScript](/guide/browser/#typescript) or want to have correct type hints in `expect`, make sure you have either `@vitest/browser/providers/playwright` or `@vitest/browser/providers/webdriverio` referenced in your [setup file](/config/#setupfile) or a [config file](/config/file) depending on the provider you use. If you use the default `preview` provider, you can specify `@vitest/browser/matchers` instead. ::: code-group -```json [preview] -{ - "compilerOptions": { - "types": [ - "@vitest/browser/matchers" - ] - } -} +```ts [preview] +/// ``` -```json [playwright] -{ - "compilerOptions": { - "types": [ - "@vitest/browser/providers/playwright" - ] - } -} +```ts [playwright] +/// ``` -```json [webdriverio] -{ - "compilerOptions": { - "types": [ - "@vitest/browser/providers/webdriverio" - ] - } -} +```ts [webdriverio] +/// ``` ::: diff --git a/docs/guide/browser/commands.md b/docs/guide/browser/commands.md index c54fc4f3199a..064ec47f418d 100644 --- a/docs/guide/browser/commands.md +++ b/docs/guide/browser/commands.md @@ -149,16 +149,10 @@ export const myCommand: BrowserCommand<[string, number]> = async ( ``` ::: tip -If you are using TypeScript, don't forget to add `@vitest/browser/providers/playwright` to your `tsconfig` "compilerOptions.types" field to get autocompletion in the config and on `userEvent` and `page` options: - -```json -{ - "compilerOptions": { - "types": [ - "@vitest/browser/providers/playwright" - ] - } -} +If you are using TypeScript, don't forget to reference `@vitest/browser/providers/playwright` in your [setup file](/config/#setupfile) or a [config file](/config/file) to get autocompletion in the config and in `userEvent` and `page` options: + +```ts +/// ``` ::: @@ -171,15 +165,9 @@ Vitest exposes some `webdriverio` specific properties on the context object. Vitest automatically switches the `webdriver` context to the test iframe by calling `browser.switchToFrame` before the command is called, so `$` and `$$` methods refer to the elements inside the iframe, not in the orchestrator, but non-webdriver APIs will still refer to the parent frame context. ::: tip -If you are using TypeScript, don't forget to add `@vitest/browser/providers/webdriverio` to your `tsconfig` "compilerOptions.types" field to get autocompletion: - -```json -{ - "compilerOptions": { - "types": [ - "@vitest/browser/providers/webdriverio" - ] - } -} +If you are using TypeScript, don't forget to reference `@vitest/browser/providers/webdriverio` in your [setup file](/config/#setupfile) or a [config file](/config/file) to get autocompletion: + +```ts +/// ``` ::: diff --git a/docs/guide/browser/index.md b/docs/guide/browser/index.md index 2d1d6b708737..a09efb8c0169 100644 --- a/docs/guide/browser/index.md +++ b/docs/guide/browser/index.md @@ -245,8 +245,6 @@ export default defineConfig({ }, }) ``` - -To have type hints, add `@vitest/browser/providers/playwright` to `compilerOptions.types` in your `tsconfig.json` file. == WebdriverIO You can configure what [options](https://webdriver.io/docs/configuration#webdriverio) Vitest should use when starting a browser via [`providerOptions`](/config/#browser-provideroptions) field: @@ -266,8 +264,6 @@ export default defineConfig({ }, }) ``` - -To have type hints, add `@vitest/browser/providers/webdriverio` to `compilerOptions.types` in your `tsconfig.json` file. ::: ## Browser Option Types @@ -284,6 +280,47 @@ The browser option in Vitest depends on the provider. Vitest will fail, if you p - `webkit` - `chromium` +## TypeScript + +By default, TypeScript doesn't recognize providers options and extra `expect` properties. If you don't use any providers, make sure the `@vitest/browser/matchers` is referenced somewhere in your tests, [setup file](/config/#setupfile) or a [config file](/config/file) to pick up the extra `expect` definitions. If you are using custom providers, make sure to add `@vitest/browser/providers/playwright` or `@vitest/browser/providers/webdriverio` to the same file so TypeScript can pick up definitions for custom options: + +::: code-block +```ts [default] +/// +``` +```ts [playwright] +/// +``` +```ts [webdriverio] +/// +``` + +Alternatively, you can also add them to `compilerOptions.types` field in your `tsconfig.json` file. Note that specifying anything in this field will disable [auto loading](https://www.typescriptlang.org/tsconfig/#types) of `@types/*` packages. + +::: code-block +```json [default] +{ + "compilerOptions": { + "types": ["@vitest/browser/matchers"] + } +} +``` +```json [playwright] +{ + "compilerOptions": { + "types": ["@vitest/browser/providers/playwright"] + } +} +``` +```json [webdriverio] +{ + "compilerOptions": { + "types": ["@vitest/browser/providers/webdriverio"] + } +} +``` +::: + ## Browser Compatibility Vitest uses [Vite dev server](https://vitejs.dev/guide/#browser-support) to run your tests, so we only support features specified in the [`esbuild.target`](https://vitejs.dev/config/shared-options.html#esbuild) option (`esnext` by default). diff --git a/docs/guide/browser/interactivity-api.md b/docs/guide/browser/interactivity-api.md index b82f4a701edb..db7576d788a5 100644 --- a/docs/guide/browser/interactivity-api.md +++ b/docs/guide/browser/interactivity-api.md @@ -12,26 +12,14 @@ import { userEvent } from '@vitest/browser/context' await userEvent.click(document.querySelector('.button')) ``` -Almost every `userEvent` method inherits its provider options. To see all available options in your IDE, add `webdriver` or `playwright` types (depending on your provider) to your `tsconfig.json` file: +Almost every `userEvent` method inherits its provider options. To see all available options in your IDE, add `webdriver` or `playwright` types (depending on your provider) to your [setup file](/config/#setupfile) or a [config file](/config/file) (depending on what is in `included` in your `tsconfig.json`): ::: code-group -```json [playwright] -{ - "compilerOptions": { - "types": [ - "@vitest/browser/providers/playwright" - ] - } -} +```ts [playwright] +/// ``` -```json [webdriverio] -{ - "compilerOptions": { - "types": [ - "@vitest/browser/providers/webdriverio" - ] - } -} +```ts [webdriverio] +/// ``` ::: diff --git a/packages/browser/dummy.js b/packages/browser/dummy.js new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/packages/browser/matchers.d.ts b/packages/browser/matchers.d.ts index bef6ff300771..8f4540f5129f 100644 --- a/packages/browser/matchers.d.ts +++ b/packages/browser/matchers.d.ts @@ -4,6 +4,7 @@ import type { Assertion } from 'vitest' declare module 'vitest' { interface JestAssertion extends jsdomMatchers.default.TestingLibraryMatchers {} + interface AsymmetricMatchersContaining extends jsdomMatchers.default.TestingLibraryMatchers {} type Promisify = { [K in keyof O]: O[K] extends (...args: infer A) => infer R diff --git a/packages/browser/package.json b/packages/browser/package.json index 7af0ce2b32e9..ed856260f4c5 100644 --- a/packages/browser/package.json +++ b/packages/browser/package.json @@ -32,13 +32,16 @@ "default": "./dist/client.js" }, "./matchers": { - "types": "./matchers.d.ts" + "types": "./matchers.d.ts", + "default": "./dummy.js" }, "./providers/webdriverio": { - "types": "./providers/webdriverio.d.ts" + "types": "./providers/webdriverio.d.ts", + "default": "./dummy.js" }, "./providers/playwright": { - "types": "./providers/playwright.d.ts" + "types": "./providers/playwright.d.ts", + "default": "./dummy.js" }, "./locator": { "types": "./dist/locators/index.d.ts",