From 296037f0c33582867238b5d075066009e81ed687 Mon Sep 17 00:00:00 2001 From: Vladimir Sheremet Date: Tue, 19 Nov 2024 14:33:42 +0100 Subject: [PATCH 1/4] docs(browser): improve typescript support --- docs/config/index.md | 14 ++++------- docs/guide/browser/assertion-api.md | 32 ++++++------------------- docs/guide/browser/commands.md | 28 +++++++--------------- docs/guide/browser/index.md | 20 ++++++++++++---- docs/guide/browser/interactivity-api.md | 22 ++++------------- packages/browser/context.d.ts | 1 + packages/browser/dummy.js | 0 packages/browser/package.json | 9 ++++--- 8 files changed, 47 insertions(+), 79 deletions(-) create mode 100644 packages/browser/dummy.js diff --git a/docs/config/index.md b/docs/config/index.md index f8c9624455b8..9238fe0c30a7 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: -```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..4bd7156c0b8b 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 tests depending on the provider you use. If you use the default `preview` provider, you can specify `@vitest/browser/context` 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..7e8d65da924e 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 or a config to get autocompletion in the config and on `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 config to get autocompletion: + +```ts +/// ``` ::: diff --git a/docs/guide/browser/index.md b/docs/guide/browser/index.md index 2d1d6b708737..6dc8cbfd6c12 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,22 @@ 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/context` is referenced somewhere in your tests or setup 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] +/// +``` +::: + ## 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..06990b40297e 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 or a config file (depennding 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/context.d.ts b/packages/browser/context.d.ts index c332b1df9de9..b4658b7dcbe4 100644 --- a/packages/browser/context.d.ts +++ b/packages/browser/context.d.ts @@ -1,5 +1,6 @@ import type { SerializedConfig } from 'vitest' import { ARIARole } from './aria-role.js' +import './matchers.js' export type BufferEncoding = | 'ascii' diff --git a/packages/browser/dummy.js b/packages/browser/dummy.js new file mode 100644 index 000000000000..e69de29bb2d1 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", From 7217185ff65e8842b6c1a87eb86b52b314d065aa Mon Sep 17 00:00:00 2001 From: Vladimir Sheremet Date: Tue, 19 Nov 2024 14:46:51 +0100 Subject: [PATCH 2/4] chore: cleanup --- packages/browser/context.d.ts | 1 - packages/browser/matchers.d.ts | 1 + 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/browser/context.d.ts b/packages/browser/context.d.ts index b4658b7dcbe4..c332b1df9de9 100644 --- a/packages/browser/context.d.ts +++ b/packages/browser/context.d.ts @@ -1,6 +1,5 @@ import type { SerializedConfig } from 'vitest' import { ARIARole } from './aria-role.js' -import './matchers.js' export type BufferEncoding = | 'ascii' 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 From 00025acb8e3ce9df0a10debaa9723c356e9da177 Mon Sep 17 00:00:00 2001 From: Vladimir Sheremet Date: Tue, 19 Nov 2024 14:47:23 +0100 Subject: [PATCH 3/4] docs: cleanup --- docs/guide/browser/assertion-api.md | 4 ++-- docs/guide/browser/index.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/guide/browser/assertion-api.md b/docs/guide/browser/assertion-api.md index 4bd7156c0b8b..512e078c1630 100644 --- a/docs/guide/browser/assertion-api.md +++ b/docs/guide/browser/assertion-api.md @@ -32,11 +32,11 @@ 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](/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 tests depending on the provider you use. If you use the default `preview` provider, you can specify `@vitest/browser/context` 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 tests depending on the provider you use. If you use the default `preview` provider, you can specify `@vitest/browser/matchers` instead. ::: code-group ```ts [preview] -/// +/// ``` ```ts [playwright] /// diff --git a/docs/guide/browser/index.md b/docs/guide/browser/index.md index 6dc8cbfd6c12..87081ad7be17 100644 --- a/docs/guide/browser/index.md +++ b/docs/guide/browser/index.md @@ -282,11 +282,11 @@ The browser option in Vitest depends on the provider. Vitest will fail, if you p ## 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/context` is referenced somewhere in your tests or setup 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: +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 or setup 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] /// From 26ae94b829c4204f946bba6449e31f335a8b8354 Mon Sep 17 00:00:00 2001 From: Vladimir Sheremet Date: Wed, 20 Nov 2024 13:21:57 +0100 Subject: [PATCH 4/4] docs: more clarify --- docs/config/index.md | 2 +- docs/guide/browser/assertion-api.md | 2 +- docs/guide/browser/commands.md | 4 ++-- docs/guide/browser/index.md | 27 ++++++++++++++++++++++++- docs/guide/browser/interactivity-api.md | 2 +- 5 files changed, 31 insertions(+), 6 deletions(-) diff --git a/docs/config/index.md b/docs/config/index.md index 9238fe0c30a7..a89a383bf959 100644 --- a/docs/config/index.md +++ b/docs/config/index.md @@ -1711,7 +1711,7 @@ export default defineConfig({ ``` ::: tip -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: +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): ```ts /// diff --git a/docs/guide/browser/assertion-api.md b/docs/guide/browser/assertion-api.md index 512e078c1630..c768cc10c1d8 100644 --- a/docs/guide/browser/assertion-api.md +++ b/docs/guide/browser/assertion-api.md @@ -32,7 +32,7 @@ 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](/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 tests 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 ```ts [preview] diff --git a/docs/guide/browser/commands.md b/docs/guide/browser/commands.md index 7e8d65da924e..064ec47f418d 100644 --- a/docs/guide/browser/commands.md +++ b/docs/guide/browser/commands.md @@ -149,7 +149,7 @@ export const myCommand: BrowserCommand<[string, number]> = async ( ``` ::: tip -If you are using TypeScript, don't forget to reference `@vitest/browser/providers/playwright` in your setup file or a config to get autocompletion in the config and on `userEvent` and `page` options: +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 /// @@ -165,7 +165,7 @@ 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 reference `@vitest/browser/providers/webdriverio` in your config to get autocompletion: +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 87081ad7be17..a09efb8c0169 100644 --- a/docs/guide/browser/index.md +++ b/docs/guide/browser/index.md @@ -282,7 +282,7 @@ The browser option in Vitest depends on the provider. Vitest will fail, if you p ## 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 or setup 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: +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] @@ -294,6 +294,31 @@ By default, TypeScript doesn't recognize providers options and extra `expect` pr ```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 diff --git a/docs/guide/browser/interactivity-api.md b/docs/guide/browser/interactivity-api.md index 06990b40297e..db7576d788a5 100644 --- a/docs/guide/browser/interactivity-api.md +++ b/docs/guide/browser/interactivity-api.md @@ -12,7 +12,7 @@ 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 setup file or a config file (depennding on what is in `included` in your `tsconfig.json`): +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 ```ts [playwright]