fix(browser): explain TypeScript support in docs and add asymmetric matchers to types (#6934)

sheremet-va · web-flow · commit ac1a7fdc628a · 2024-11-25T17:00:47.000+01:00
diff --git 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
+/// <reference types="@vitest/browser/providers/playwright" />
+/// <reference types="@vitest/browser/providers/webdriverio" />
 ```
 :::
 
diff --git 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]
+/// <reference types="@vitest/browser/matchers" />
 ```
-```json [playwright]
-{
-  "compilerOptions": {
-    "types": [
-      "@vitest/browser/providers/playwright"
-    ]
-  }
-}
+```ts [playwright]
+/// <reference types="@vitest/browser/providers/playwright" />
 ```
-```json [webdriverio]
-{
-  "compilerOptions": {
-    "types": [
-      "@vitest/browser/providers/webdriverio"
-    ]
-  }
-}
+```ts [webdriverio]
+/// <reference types="@vitest/browser/providers/webdriverio" />
 ```
 :::
 
diff --git 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
+/// <reference types="@vitest/browser/providers/playwright" />
 ```
 :::
 
@@ -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
+/// <reference types="@vitest/browser/providers/webdriverio" />
 ```
 :::
diff --git 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]
+/// <reference types="@vitest/browser/matchers" />
+```
+```ts [playwright]
+/// <reference types="@vitest/browser/providers/playwright" />
+```
+```ts [webdriverio]
+/// <reference types="@vitest/browser/providers/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
@@ -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]
+/// <reference types="@vitest/browser/providers/playwright" />
 ```
-```json [webdriverio]
-{
-  "compilerOptions": {
-    "types": [
-      "@vitest/browser/providers/webdriverio"
-    ]
-  }
-}
+```ts [webdriverio]
+/// <reference types="@vitest/browser/providers/webdriverio" />
 ```
 :::
 
diff --git a/packages/browser/dummy.js b/packages/browser/dummy.js
diff --git 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<T = any> extends jsdomMatchers.default.TestingLibraryMatchers<void, T> {}
+  interface AsymmetricMatchersContaining extends jsdomMatchers.default.TestingLibraryMatchers<void, void> {}
 
   type Promisify<O> = {
     [K in keyof O]: O[K] extends (...args: infer A) => infer R
diff --git 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",
