vitest 1.6.0 → 2.0.0-beta.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. package/LICENSE.md +173 -1
  2. package/dist/browser.d.ts +22 -2
  3. package/dist/browser.js +6 -4
  4. package/dist/chunks/{environments-node.vcoXCoKs.js → environments-node.39w4gmlF.js} +2 -2
  5. package/dist/chunks/{install-pkg.LE8oaA1t.js → install-pkg.DNUmWFkO.js} +2 -2
  6. package/dist/chunks/integrations-globals.C6Ah-pUW.js +31 -0
  7. package/dist/chunks/{runtime-console.EO5ha7qv.js → runtime-console.DiVMr5d4.js} +62 -32
  8. package/dist/chunks/{runtime-runBaseTests.oAvMKtQC.js → runtime-runBaseTests.Cukyr5-I.js} +18 -18
  9. package/dist/cli.js +3 -3
  10. package/dist/config.cjs +4 -5
  11. package/dist/config.d.ts +2 -2
  12. package/dist/config.js +4 -5
  13. package/dist/coverage.d.ts +1 -1
  14. package/dist/coverage.js +34 -8
  15. package/dist/environments.d.ts +1 -1
  16. package/dist/environments.js +1 -1
  17. package/dist/execute.d.ts +3 -2
  18. package/dist/execute.js +2 -2
  19. package/dist/index.d.ts +777 -65
  20. package/dist/index.js +12 -12
  21. package/dist/node.d.ts +7 -7
  22. package/dist/node.js +24 -23
  23. package/dist/{reporters-yx5ZTtEV.d.ts → reporters-CYVC6LOl.d.ts} +439 -219
  24. package/dist/reporters.d.ts +1 -1
  25. package/dist/reporters.js +11 -12
  26. package/dist/runners.d.ts +4 -2
  27. package/dist/runners.js +25 -18
  28. package/dist/snapshot.js +3 -3
  29. package/dist/{suite-IbNSsUWN.d.ts → suite-Dpu9EC_k.d.ts} +1 -1
  30. package/dist/suite.d.ts +2 -2
  31. package/dist/suite.js +4 -4
  32. package/dist/vendor/{base.Ybri3C14.js → base.Dln9yllP.js} +3 -3
  33. package/dist/vendor/{base.5NT-gWu5.js → base._gnK9Slw.js} +1 -2
  34. package/dist/vendor/{benchmark.yGkUTKnC.js → benchmark.BNLebNi5.js} +1 -1
  35. package/dist/vendor/{cac.EdDItJD-.js → cac.CtYFkoSJ.js} +66 -25
  36. package/dist/vendor/{cli-api.E07AF1Yq.js → cli-api.CUtJc4r3.js} +11851 -7276
  37. package/dist/vendor/{constants.5J7I254_.js → constants.TCjCaw2D.js} +4 -3
  38. package/dist/vendor/{execute.fL3szUAI.js → execute.BHj6OMh4.js} +4 -4
  39. package/dist/vendor/{index.DpVgvm2P.js → index.B5SKBLvV.js} +5 -5
  40. package/dist/vendor/{index.Q04MCqDO.js → index.BOMEjpjj.js} +680 -160
  41. package/dist/vendor/{index.8bPxjt7g.js → index.BpSiYbpB.js} +5 -1
  42. package/dist/vendor/{index.xL8XjTLv.js → index.CThipSqB.js} +2538 -2525
  43. package/dist/vendor/{index.dI9lHwVn.js → index.D3hs2WiI.js} +8 -6
  44. package/dist/vendor/{index.SMVOaj7F.js → index._7XLd8Kd.js} +2 -2
  45. package/dist/vendor/{index.GVFv9dZ0.js → index.kpsSqFiz.js} +2 -1
  46. package/dist/vendor/{rpc.joBhAkyK.js → rpc.DRDE9Pu1.js} +2 -2
  47. package/dist/vendor/{run-once.Olz_Zkd8.js → run-once.DLomgGUH.js} +1 -1
  48. package/dist/vendor/{setup-common.8nJLd4ay.js → setup-common.DAu7t7mY.js} +2 -2
  49. package/dist/vendor/spy.Cf_4R5Oe.js +22 -0
  50. package/dist/vendor/{tasks.IknbGB2n.js → tasks.WC7M-K-v.js} +4 -1
  51. package/dist/vendor/{utils.dEtNIEgr.js → utils.YuQ3LT2a.js} +2 -2
  52. package/dist/vendor/{vi.YFlodzP_.js → vi.hATFzZbX.js} +124 -56
  53. package/dist/vendor/{vm.QEE48c0T.js → vm.Ow-X2mkS.js} +47 -59
  54. package/dist/worker.js +6 -6
  55. package/dist/workers/forks.js +5 -5
  56. package/dist/workers/runVmTests.js +17 -17
  57. package/dist/workers/threads.js +5 -5
  58. package/dist/workers/vmForks.js +8 -8
  59. package/dist/workers/vmThreads.js +8 -8
  60. package/dist/workers.d.ts +1 -1
  61. package/dist/workers.js +13 -13
  62. package/package.json +35 -35
  63. package/suppress-warnings.cjs +2 -1
  64. package/vitest.mjs +1 -1
  65. package/dist/chunks/integrations-globals.kw4co3rx.js +0 -31
  66. package/dist/cli-wrapper.js +0 -119
  67. /package/dist/chunks/{node-git.Hw101KjS.js → node-git.CCI8evVZ.js} +0 -0
  68. /package/dist/vendor/{_commonjsHelpers.jjO7Zipk.js → _commonjsHelpers.BFTU3MAI.js} +0 -0
  69. /package/dist/vendor/{coverage.E7sG1b3r.js → coverage.ChSqD-qS.js} +0 -0
  70. /package/dist/vendor/{date.Ns1pGd_X.js → date.BKM1wewY.js} +0 -0
  71. /package/dist/vendor/{env.AtSIuHFg.js → env.bmJgw1qP.js} +0 -0
  72. /package/dist/vendor/{global.CkGT_TMy.js → global.7bFbnyXl.js} +0 -0
  73. /package/dist/vendor/{inspector.IgLX3ur5.js → inspector.hPQncR7V.js} +0 -0
  74. /package/dist/vendor/{utils.0uYuCbzo.js → utils.CUjzkRH7.js} +0 -0
package/dist/index.d.ts CHANGED
@@ -1,23 +1,21 @@
1
- import { TaskPopulated, File, TaskResultPack, CancelReason } from '@vitest/runner';
1
+ import { TaskPopulated } from '@vitest/runner';
2
2
  export { Custom, DoneCallback, ExtendedContext, File, HookCleanupCallback, HookListener, OnTestFailedHandler, RunMode, RuntimeContext, SequenceHooks, SequenceSetupFiles, Suite, SuiteAPI, SuiteCollector, SuiteFactory, SuiteHooks, Task, TaskBase, TaskContext, TaskCustomOptions, TaskMeta, TaskResult, TaskResultPack, TaskState, Test, TestAPI, TestContext, TestFunction, TestOptions, afterAll, afterEach, beforeAll, beforeEach, describe, it, onTestFailed, onTestFinished, suite, test } from '@vitest/runner';
3
- export { b as bench } from './suite-IbNSsUWN.js';
3
+ export { b as bench } from './suite-Dpu9EC_k.js';
4
4
  import { ExpectStatic } from '@vitest/expect';
5
5
  export { Assertion, AsymmetricMatchersContaining, ExpectStatic, JestAssertion } from '@vitest/expect';
6
- import { F as FakeTimerInstallOpts, M as MockFactoryWithHelper, s as RuntimeConfig, P as ProvidedContext, A as AfterSuiteRunMeta, t as UserConsoleLog, R as ResolvedConfig, u as ModuleGraphData, v as Reporter } from './reporters-yx5ZTtEV.js';
7
- export { Q as ApiConfig, aa as ArgumentsType, a9 as Arrayable, a7 as Awaitable, B as BaseCoverageOptions, ap as BenchFunction, an as Benchmark, aq as BenchmarkAPI, ao as BenchmarkResult, am as BenchmarkUserOptions, a0 as BrowserConfigOptions, r as BrowserScript, L as BuiltinEnvironment, O as CSSModuleScopeStrategy, y as CollectLineNumbers, z as CollectLines, ac as Constructable, G as Context, f as ContextRPC, a3 as ContextTestEnvironment, aj as CoverageIstanbulOptions, C as CoverageOptions, b as CoverageProvider, c as CoverageProviderModule, ai as CoverageReporter, ak as CoverageV8Options, al as CustomProviderOptions, X as DepsOptimizationOptions, E as Environment, S as EnvironmentOptions, ae as EnvironmentReturn, K as HappyDOMOptions, Z as InlineConfig, J as JSDOMOptions, ad as ModuleCache, ab as MutableArray, a8 as Nullable, ag as OnServerRestartHandler, H as Pool, I as PoolOptions, $ as ProjectConfig, w as RawErrsMap, ah as ReportContext, a5 as ResolveIdFunction, a as ResolvedCoverageOptions, a4 as ResolvedTestEnvironment, D as RootAndTarget, a2 as RunnerRPC, e as RuntimeRPC, Y as TransformModePatterns, x as TscErrorInfo, _ as TypecheckConfig, U as UserConfig, a1 as UserWorkspaceConfig, i as Vitest, N as VitestEnvironment, V as VitestRunMode, af as VmEnvironmentReturn, g as WorkerContext, W as WorkerGlobalState, a6 as WorkerRPC } from './reporters-yx5ZTtEV.js';
6
+ import { F as FakeTimerInstallOpts, M as MockFactoryWithHelper, h as RuntimeConfig, P as ProvidedContext } from './reporters-CYVC6LOl.js';
7
+ export { Q as AfterSuiteRunMeta, A as ApiConfig, $ as ArgumentsType, _ as Arrayable, Y as Awaitable, B as BaseCoverageOptions, ag as BenchFunction, ae as Benchmark, ah as BenchmarkAPI, af as BenchmarkResult, ad as BenchmarkUserOptions, x as BrowserConfigOptions, w as BrowserScript, p as BuiltinEnvironment, q as CSSModuleScopeStrategy, j as CollectLineNumbers, k as CollectLines, a1 as Constructable, m as Context, f as ContextRPC, G as ContextTestEnvironment, aa as CoverageIstanbulOptions, C as CoverageOptions, b as CoverageProvider, c as CoverageProviderModule, a9 as CoverageReporter, ab as CoverageV8Options, ac as CustomProviderOptions, D as DepsOptimizationOptions, E as Environment, r as EnvironmentOptions, a3 as EnvironmentReturn, H as HappyDOMOptions, I as InlineConfig, J as JSDOMOptions, a2 as ModuleCache, a6 as ModuleGraphData, a0 as MutableArray, Z as Nullable, a7 as OnServerRestartHandler, n as Pool, o as PoolOptions, v as ProjectConfig, i as RawErrsMap, a8 as ReportContext, N as Reporter, O as ResolveIdFunction, R as ResolvedConfig, a as ResolvedCoverageOptions, K as ResolvedTestEnvironment, l as RootAndTarget, z as RunnerRPC, e as RuntimeRPC, S as SerializableSpec, t as TransformModePatterns, ai as TransformResultWithSource, T as TscErrorInfo, u as TypecheckConfig, U as UserConfig, a5 as UserConsoleLog, y as UserWorkspaceConfig, L as Vitest, V as VitestEnvironment, s as VitestRunMode, a4 as VmEnvironmentReturn, am as WebSocketBrowserEvents, ak as WebSocketBrowserHandlers, ao as WebSocketBrowserRPC, al as WebSocketEvents, aj as WebSocketHandlers, an as WebSocketRPC, g as WorkerContext, W as WorkerGlobalState, X as WorkerRPC } from './reporters-CYVC6LOl.js';
8
8
  import { spyOn, fn, MaybeMockedDeep, MaybeMocked, MaybePartiallyMocked, MaybePartiallyMockedDeep, MockInstance } from '@vitest/spy';
9
9
  export { Mock, MockContext, MockInstance, Mocked, MockedClass, MockedFunction, MockedObject, SpyInstance } from '@vitest/spy';
10
- export { SnapshotEnvironment } from '@vitest/snapshot/environment';
11
- import { SnapshotResult } from '@vitest/snapshot';
12
10
  export { SnapshotData, SnapshotMatchOptions, SnapshotResult, SnapshotSerializer, SnapshotStateOptions, SnapshotSummary, SnapshotUpdateState, UncheckedSnapshot } from '@vitest/snapshot';
13
11
  export { DiffOptions } from '@vitest/utils/diff';
14
- import { TransformResult } from 'vite';
15
12
  import * as chai from 'chai';
16
13
  export { chai };
17
14
  export { assert, should } from 'chai';
18
15
  export { ErrorWithDiff, ParsedStack } from '@vitest/utils';
19
16
  export { Bench as BenchFactory, Options as BenchOptions, Task as BenchTask, TaskResult as BenchTaskResult } from 'tinybench';
20
17
  import '@vitest/runner/utils';
18
+ import 'vite';
21
19
  import 'vite-node';
22
20
  import 'node:stream';
23
21
  import 'vite-node/client';
@@ -26,20 +24,50 @@ import 'vite-node/server';
26
24
  import 'node:worker_threads';
27
25
  import 'node:fs';
28
26
 
27
+ /**
28
+ * Negates a boolean type.
29
+ */
29
30
  declare type Not<T extends boolean> = T extends true ? false : true;
31
+ /**
32
+ * Checks if all the boolean types in the {@linkcode Types} array are `true`.
33
+ */
30
34
  declare type And<Types extends boolean[]> = Types[number] extends true ? true : false;
35
+ /**
36
+ * Represents an equality type that returns {@linkcode Right} if
37
+ * {@linkcode Left} is `true`,
38
+ * otherwise returns the negation of {@linkcode Right}.
39
+ */
31
40
  declare type Eq<Left extends boolean, Right extends boolean> = Left extends true ? Right : Not<Right>;
32
41
  declare const secret: unique symbol;
33
42
  declare type Secret = typeof secret;
43
+ /**
44
+ * Checks if the given type is `never`.
45
+ */
34
46
  declare type IsNever<T> = [T] extends [never] ? true : false;
47
+ /**
48
+ * Checks if the given type is `any`.
49
+ */
35
50
  declare type IsAny<T> = [T] extends [Secret] ? Not<IsNever<T>> : false;
51
+ /**
52
+ * Determines if the given type is `unknown`.
53
+ */
36
54
  declare type IsUnknown<T> = [unknown] extends [T] ? Not<IsAny<T>> : false;
55
+ /**
56
+ * Determines the printable type representation for a given type.
57
+ */
37
58
  declare type PrintType<T> = IsUnknown<T> extends true ? 'unknown' : IsNever<T> extends true ? 'never' : IsAny<T> extends true ? never : boolean extends T ? 'boolean' : T extends boolean ? `literal boolean: ${T}` : string extends T ? 'string' : T extends string ? `literal string: ${T}` : number extends T ? 'number' : T extends number ? `literal number: ${T}` : T extends null ? 'null' : T extends undefined ? 'undefined' : T extends (...args: any[]) => any ? 'function' : '...';
38
- /** Subjective "useful" keys from a type. For objects it's just `keyof` but for tuples/arrays it's the number keys
59
+ /**
60
+ * Subjective "useful" keys from a type. For objects it's just `keyof` but for
61
+ * tuples/arrays it's the number keys.
62
+ *
39
63
  * @example
64
+ * ```ts
40
65
  * UsefulKeys<{a: 1; b: 2}> // 'a' | 'b'
66
+ *
41
67
  * UsefulKeys<['a', 'b']> // '0' | '1'
68
+ *
42
69
  * UsefulKeys<string[]> // number
70
+ * ```
43
71
  */
44
72
  declare type UsefulKeys<T> = T extends any[] ? {
45
73
  [K in keyof T]: K;
@@ -48,15 +76,20 @@ declare type MismatchInfo<Actual, Expected> = And<[Extends<PrintType<Actual>, '.
48
76
  [K in UsefulKeys<Actual> | UsefulKeys<Expected>]: MismatchInfo<K extends keyof Actual ? Actual[K] : never, K extends keyof Expected ? Expected[K] : never>;
49
77
  } : StrictEqualUsingBranding<Actual, Expected> extends true ? Actual : `Expected: ${PrintType<Expected>}, Actual: ${PrintType<Exclude<Actual, Expected>>}`;
50
78
  /**
51
- * Recursively walk a type and replace it with a branded type related to the original. This is useful for
52
- * equality-checking stricter than `A extends B ? B extends A ? true : false : false`, because it detects
53
- * the difference between a few edge-case types that vanilla typescript doesn't by default:
79
+ * Represents a deeply branded type.
80
+ *
81
+ * Recursively walk a type and replace it with a branded type related to the
82
+ * original. This is useful for equality-checking stricter than
83
+ * `A extends B ? B extends A ? true : false : false`, because it detects the
84
+ * difference between a few edge-case types that vanilla typescript
85
+ * doesn't by default:
54
86
  * - `any` vs `unknown`
55
87
  * - `{ readonly a: string }` vs `{ a: string }`
56
88
  * - `{ a?: string }` vs `{ a: string | undefined }`
57
89
  *
58
- * Note: not very performant for complex types - this should only be used when you know you need it. If doing
59
- * an equality check, it's almost always better to use `StrictEqualUsingTSInternalIdenticalToOperator`.
90
+ * __Note__: not very performant for complex types - this should only be used
91
+ * when you know you need it. If doing an equality check, it's almost always
92
+ * better to use {@linkcode StrictEqualUsingTSInternalIdenticalToOperator}.
60
93
  */
61
94
  declare type DeepBrand<T> = IsNever<T> extends true ? {
62
95
  type: 'never';
@@ -92,10 +125,19 @@ declare type DeepBrand<T> = IsNever<T> extends true ? {
92
125
  optional: OptionalKeys<T>;
93
126
  constructorParams: DeepBrand<ConstructorParams<T>>;
94
127
  };
128
+ /**
129
+ * Extracts the keys from a type that are required (not optional).
130
+ */
95
131
  declare type RequiredKeys<T> = Extract<{
96
132
  [K in keyof T]-?: {} extends Pick<T, K> ? never : K;
97
133
  }[keyof T], keyof T>;
134
+ /**
135
+ * Gets the keys of an object type that are optional.
136
+ */
98
137
  declare type OptionalKeys<T> = Exclude<keyof T, RequiredKeys<T>>;
138
+ /**
139
+ * Extracts the keys from a type that are not readonly.
140
+ */
99
141
  declare type ReadonlyKeys<T> = Extract<{
100
142
  [K in keyof T]-?: ReadonlyEquivalent<{
101
143
  [_K in K]: T[K];
@@ -103,27 +145,66 @@ declare type ReadonlyKeys<T> = Extract<{
103
145
  -readonly [_K in K]: T[K];
104
146
  }> extends true ? never : K;
105
147
  }[keyof T], keyof T>;
148
+ /**
149
+ * Determines if two types, are equivalent in a `readonly` manner.
150
+ */
106
151
  declare type ReadonlyEquivalent<X, Y> = Extends<(<T>() => T extends X ? true : false), (<T>() => T extends Y ? true : false)>;
107
- /** Returns true if `L extends R`. Explicitly checks for `never` since that can give unexpected results. */
152
+ /**
153
+ * Checks if one type extends another.
154
+ */
108
155
  declare type Extends<L, R> = IsNever<L> extends true ? IsNever<R> : [L] extends [R] ? true : false;
109
156
  declare type ExtendsUsingBranding<L, R> = Extends<DeepBrand<L>, DeepBrand<R>>;
110
157
  declare type ExtendsExcludingAnyOrNever<L, R> = IsAny<L> extends true ? IsAny<R> : Extends<L, R>;
158
+ /**
159
+ * Checks if two types are strictly equal using
160
+ * the TypeScript internal identical-to operator.
161
+ *
162
+ * @see {@link https://github.com/microsoft/TypeScript/issues/55188#issuecomment-1656328122 much history}
163
+ */
111
164
  declare type StrictEqualUsingTSInternalIdenticalToOperator<L, R> = (<T>() => T extends (L & T) | T ? true : false) extends <T>() => T extends (R & T) | T ? true : false ? IsNever<L> extends IsNever<R> ? true : false : false;
165
+ /**
166
+ * Checks if two types are strictly equal using branding.
167
+ */
112
168
  declare type StrictEqualUsingBranding<Left, Right> = And<[
113
169
  ExtendsUsingBranding<Left, Right>,
114
170
  ExtendsUsingBranding<Right, Left>
115
171
  ]>;
116
- declare type Params<Actual> = Actual extends (...args: infer P) => any ? P : never;
172
+ /**
173
+ * Extracts the parameter types from a function type.
174
+ */
175
+ declare type Params<Actual> = Actual extends (...args: infer ParameterTypes) => any ? ParameterTypes : never;
176
+ /**
177
+ * Represents the constructor parameters of a class or constructor function.
178
+ * If the constructor takes no arguments, an empty array is returned.
179
+ */
117
180
  declare type ConstructorParams<Actual> = Actual extends new (...args: infer P) => any ? Actual extends new () => any ? P | [] : P : never;
118
181
  declare const mismatch: unique symbol;
119
182
  declare type Mismatch = {
120
183
  [mismatch]: 'mismatch';
121
184
  };
122
- /** A type which should match anything passed as a value but *doesn't* match `Mismatch` - helps TypeScript select the right overload for `toEqualTypeOf` and `toMatchTypeOf`. */
185
+ /**
186
+ * A type which should match anything passed as a value but *doesn't*
187
+ * match {@linkcode Mismatch}. It helps TypeScript select the right overload
188
+ * for {@linkcode PositiveExpectTypeOf.toEqualTypeOf `.toEqualTypeOf()`} and
189
+ * {@linkcode PositiveExpectTypeOf.toMatchTypeOf `.toMatchTypeOf()`}.
190
+ */
123
191
  declare const avalue: unique symbol;
192
+ /**
193
+ * Represents a value that can be of various types.
194
+ */
124
195
  declare type AValue = {
125
196
  [avalue]?: undefined;
126
197
  } | string | number | boolean | symbol | bigint | null | undefined | void;
198
+ /**
199
+ * Represents the type of mismatched arguments between
200
+ * the actual result and the expected result.
201
+ *
202
+ * If {@linkcode ActualResult} and {@linkcode ExpectedResult} are equivalent,
203
+ * the type resolves to an empty tuple `[]`, indicating no mismatch.
204
+ * If they are not equivalent, it resolves to a tuple containing the element
205
+ * {@linkcode Mismatch}, signifying a discrepancy between
206
+ * the expected and actual results.
207
+ */
127
208
  declare type MismatchArgs<ActualResult extends boolean, ExpectedResult extends boolean> = Eq<ActualResult, ExpectedResult> extends true ? [] : [Mismatch];
128
209
  declare const inverted: unique symbol;
129
210
  declare type Inverted<T> = {
@@ -199,85 +280,746 @@ declare type ExpectNullable<T> = {
199
280
  [expectNullable]: T;
200
281
  result: Not<StrictEqualUsingBranding<T, NonNullable<T>>>;
201
282
  };
283
+ /**
284
+ * Represents a scolder function that checks if the result of an expecter
285
+ * matches the specified options.
286
+ */
202
287
  declare type Scolder<Expecter extends {
203
288
  result: boolean;
204
289
  }, Options extends {
205
290
  positive: boolean;
206
291
  }> = Expecter['result'] extends Options['positive'] ? () => true : Options['positive'] extends true ? Expecter : Inverted<Expecter>;
292
+ /**
293
+ * Represents the positive assertion methods available for type checking in the
294
+ * {@linkcode expectTypeOf()} utility.
295
+ */
207
296
  interface PositiveExpectTypeOf<Actual> extends BaseExpectTypeOf<Actual, {
208
297
  positive: true;
209
298
  branded: false;
210
299
  }> {
211
300
  toEqualTypeOf: {
301
+ /**
302
+ * Uses TypeScript's internal technique to check for type "identicalness".
303
+ *
304
+ * It will check if the types are fully equal to each other.
305
+ * It will not fail if two objects have different values, but the same type.
306
+ * It will fail however if an object is missing a property.
307
+ *
308
+ * **_Unexpected failure_**? For a more permissive but less performant
309
+ * check that accommodates for equivalent intersection types,
310
+ * use {@linkcode branded `.branded.toEqualTypeOf()`}.
311
+ * @see {@link https://github.com/mmkal/expect-type#why-is-my-assertion-failing The documentation for details}.
312
+ *
313
+ * @example
314
+ * <caption>Using generic type argument syntax</caption>
315
+ * ```ts
316
+ * expectTypeOf({ a: 1 }).toEqualTypeOf<{ a: number }>()
317
+ *
318
+ * expectTypeOf({ a: 1, b: 1 }).not.toEqualTypeOf<{ a: number }>()
319
+ * ```
320
+ *
321
+ * @example
322
+ * <caption>Using inferred type syntax by passing a value</caption>
323
+ * ```ts
324
+ * expectTypeOf({ a: 1 }).toEqualTypeOf({ a: 1 })
325
+ *
326
+ * expectTypeOf({ a: 1 }).toEqualTypeOf({ a: 2 })
327
+ * ```
328
+ *
329
+ * @param value - The value to compare against the expected type.
330
+ * @param MISMATCH - The mismatch arguments.
331
+ * @returns `true`.
332
+ */
212
333
  <Expected extends StrictEqualUsingTSInternalIdenticalToOperator<Actual, Expected> extends true ? unknown : MismatchInfo<Actual, Expected>>(value: Expected & AValue, // reason for `& AValue`: make sure this is only the selected overload when the end-user passes a value for an inferred typearg. The `Mismatch` type does match `AValue`.
213
334
  ...MISMATCH: MismatchArgs<StrictEqualUsingTSInternalIdenticalToOperator<Actual, Expected>, true>): true;
335
+ /**
336
+ * Uses TypeScript's internal technique to check for type "identicalness".
337
+ *
338
+ * It will check if the types are fully equal to each other.
339
+ * It will not fail if two objects have different values, but the same type.
340
+ * It will fail however if an object is missing a property.
341
+ *
342
+ * **_Unexpected failure_**? For a more permissive but less performant
343
+ * check that accommodates for equivalent intersection types,
344
+ * use {@linkcode branded `.branded.toEqualTypeOf()`}.
345
+ * @see {@link https://github.com/mmkal/expect-type#why-is-my-assertion-failing The documentation for details}.
346
+ *
347
+ * @example
348
+ * <caption>Using generic type argument syntax</caption>
349
+ * ```ts
350
+ * expectTypeOf({ a: 1 }).toEqualTypeOf<{ a: number }>()
351
+ *
352
+ * expectTypeOf({ a: 1, b: 1 }).not.toEqualTypeOf<{ a: number }>()
353
+ * ```
354
+ *
355
+ * @example
356
+ * <caption>Using inferred type syntax by passing a value</caption>
357
+ * ```ts
358
+ * expectTypeOf({ a: 1 }).toEqualTypeOf({ a: 1 })
359
+ *
360
+ * expectTypeOf({ a: 1 }).toEqualTypeOf({ a: 2 })
361
+ * ```
362
+ *
363
+ * @param MISMATCH - The mismatch arguments.
364
+ * @returns `true`.
365
+ */
214
366
  <Expected extends StrictEqualUsingTSInternalIdenticalToOperator<Actual, Expected> extends true ? unknown : MismatchInfo<Actual, Expected>>(...MISMATCH: MismatchArgs<StrictEqualUsingTSInternalIdenticalToOperator<Actual, Expected>, true>): true;
215
367
  };
216
368
  toMatchTypeOf: {
369
+ /**
370
+ * A less strict version of {@linkcode toEqualTypeOf `.toEqualTypeOf()`}
371
+ * that allows for extra properties.
372
+ * This is roughly equivalent to an `extends` constraint
373
+ * in a function type argument.
374
+ *
375
+ * @example
376
+ * <caption>Using generic type argument syntax</caption>
377
+ * ```ts
378
+ * expectTypeOf({ a: 1, b: 1 }).toMatchTypeOf<{ a: number }>()
379
+ * ```
380
+ *
381
+ * @example
382
+ * <caption>Using inferred type syntax by passing a value</caption>
383
+ * ```ts
384
+ * expectTypeOf({ a: 1, b: 1 }).toMatchTypeOf({ a: 2 })
385
+ * ```
386
+ *
387
+ * @param value - The value to compare against the expected type.
388
+ * @param MISMATCH - The mismatch arguments.
389
+ * @returns `true`.
390
+ */
217
391
  <Expected extends Extends<Actual, Expected> extends true ? unknown : MismatchInfo<Actual, Expected>>(value: Expected & AValue, // reason for `& AValue`: make sure this is only the selected overload when the end-user passes a value for an inferred typearg. The `Mismatch` type does match `AValue`.
218
392
  ...MISMATCH: MismatchArgs<Extends<Actual, Expected>, true>): true;
393
+ /**
394
+ * A less strict version of {@linkcode toEqualTypeOf `.toEqualTypeOf()`}
395
+ * that allows for extra properties.
396
+ * This is roughly equivalent to an `extends` constraint
397
+ * in a function type argument.
398
+ *
399
+ * @example
400
+ * <caption>Using generic type argument syntax</caption>
401
+ * ```ts
402
+ * expectTypeOf({ a: 1, b: 1 }).toMatchTypeOf<{ a: number }>()
403
+ * ```
404
+ *
405
+ * @example
406
+ * <caption>Using inferred type syntax by passing a value</caption>
407
+ * ```ts
408
+ * expectTypeOf({ a: 1, b: 1 }).toMatchTypeOf({ a: 2 })
409
+ * ```
410
+ *
411
+ * @param MISMATCH - The mismatch arguments.
412
+ * @returns `true`.
413
+ */
219
414
  <Expected extends Extends<Actual, Expected> extends true ? unknown : MismatchInfo<Actual, Expected>>(...MISMATCH: MismatchArgs<Extends<Actual, Expected>, true>): true;
220
415
  };
221
- toHaveProperty: <K extends keyof Actual>(key: K, ...MISMATCH: MismatchArgs<Extends<K, keyof Actual>, true>) => K extends keyof Actual ? PositiveExpectTypeOf<Actual[K]> : true;
416
+ /**
417
+ * Checks whether an object has a given property.
418
+ *
419
+ * @example
420
+ * <caption>check that properties exist</caption>
421
+ * ```ts
422
+ * const obj = {a: 1, b: ''}
423
+ *
424
+ * expectTypeOf(obj).toHaveProperty('a')
425
+ *
426
+ * expectTypeOf(obj).not.toHaveProperty('c')
427
+ * ```
428
+ *
429
+ * @param key - The property key to check for.
430
+ * @param MISMATCH - The mismatch arguments.
431
+ * @returns `true`.
432
+ */
433
+ toHaveProperty: <KeyType extends keyof Actual>(key: KeyType, ...MISMATCH: MismatchArgs<Extends<KeyType, keyof Actual>, true>) => KeyType extends keyof Actual ? PositiveExpectTypeOf<Actual[KeyType]> : true;
434
+ /**
435
+ * Inverts the result of the following assertions.
436
+ *
437
+ * @example
438
+ * ```ts
439
+ * expectTypeOf({ a: 1 }).not.toMatchTypeOf({ b: 1 })
440
+ * ```
441
+ */
222
442
  not: NegativeExpectTypeOf<Actual>;
443
+ /**
444
+ * Intersection types can cause issues with
445
+ * {@linkcode toEqualTypeOf `.toEqualTypeOf()`}:
446
+ * ```ts
447
+ * // ❌ The following line doesn't compile, even though the types are arguably the same.
448
+ * expectTypeOf<{ a: 1 } & { b: 2 }>().toEqualTypeOf<{ a: 1; b: 2 }>()
449
+ * ```
450
+ * This helper works around this problem by using
451
+ * a more permissive but less performant check.
452
+ *
453
+ * __Note__: This comes at a performance cost, and can cause the compiler
454
+ * to 'give up' if used with excessively deep types, so use sparingly.
455
+ *
456
+ * @see {@link https://github.com/mmkal/expect-type/pull/21 Reference}
457
+ */
223
458
  branded: {
459
+ /**
460
+ * Uses TypeScript's internal technique to check for type "identicalness".
461
+ *
462
+ * It will check if the types are fully equal to each other.
463
+ * It will not fail if two objects have different values, but the same type.
464
+ * It will fail however if an object is missing a property.
465
+ *
466
+ * **_Unexpected failure_**? For a more permissive but less performant
467
+ * check that accommodates for equivalent intersection types,
468
+ * use {@linkcode PositiveExpectTypeOf.branded `.branded.toEqualTypeOf()`}.
469
+ * @see {@link https://github.com/mmkal/expect-type#why-is-my-assertion-failing The documentation for details}.
470
+ *
471
+ * @example
472
+ * <caption>Using generic type argument syntax</caption>
473
+ * ```ts
474
+ * expectTypeOf({ a: 1 }).toEqualTypeOf<{ a: number }>()
475
+ *
476
+ * expectTypeOf({ a: 1, b: 1 }).not.toEqualTypeOf<{ a: number }>()
477
+ * ```
478
+ *
479
+ * @example
480
+ * <caption>Using inferred type syntax by passing a value</caption>
481
+ * ```ts
482
+ * expectTypeOf({ a: 1 }).toEqualTypeOf({ a: 1 })
483
+ *
484
+ * expectTypeOf({ a: 1 }).toEqualTypeOf({ a: 2 })
485
+ * ```
486
+ *
487
+ * @param MISMATCH - The mismatch arguments.
488
+ * @returns `true`.
489
+ */
224
490
  toEqualTypeOf: <Expected extends StrictEqualUsingBranding<Actual, Expected> extends true ? unknown : MismatchInfo<Actual, Expected>>(...MISMATCH: MismatchArgs<StrictEqualUsingBranding<Actual, Expected>, true>) => true;
225
491
  };
226
492
  }
493
+ /**
494
+ * Represents the negative expectation type for the {@linkcode Actual} type.
495
+ */
227
496
  interface NegativeExpectTypeOf<Actual> extends BaseExpectTypeOf<Actual, {
228
497
  positive: false;
229
498
  }> {
230
499
  toEqualTypeOf: {
500
+ /**
501
+ * Uses TypeScript's internal technique to check for type "identicalness".
502
+ *
503
+ * It will check if the types are fully equal to each other.
504
+ * It will not fail if two objects have different values, but the same type.
505
+ * It will fail however if an object is missing a property.
506
+ *
507
+ * **_Unexpected failure_**? For a more permissive but less performant
508
+ * check that accommodates for equivalent intersection types,
509
+ * use {@linkcode PositiveExpectTypeOf.branded `.branded.toEqualTypeOf()`}.
510
+ * @see {@link https://github.com/mmkal/expect-type#why-is-my-assertion-failing The documentation for details}.
511
+ *
512
+ * @example
513
+ * <caption>Using generic type argument syntax</caption>
514
+ * ```ts
515
+ * expectTypeOf({ a: 1 }).toEqualTypeOf<{ a: number }>()
516
+ *
517
+ * expectTypeOf({ a: 1, b: 1 }).not.toEqualTypeOf<{ a: number }>()
518
+ * ```
519
+ *
520
+ * @example
521
+ * <caption>Using inferred type syntax by passing a value</caption>
522
+ * ```ts
523
+ * expectTypeOf({ a: 1 }).toEqualTypeOf({ a: 1 })
524
+ *
525
+ * expectTypeOf({ a: 1 }).toEqualTypeOf({ a: 2 })
526
+ * ```
527
+ *
528
+ * @param value - The value to compare against the expected type.
529
+ * @param MISMATCH - The mismatch arguments.
530
+ * @returns `true`.
531
+ */
231
532
  <Expected>(value: Expected & AValue, ...MISMATCH: MismatchArgs<StrictEqualUsingTSInternalIdenticalToOperator<Actual, Expected>, false>): true;
533
+ /**
534
+ * Uses TypeScript's internal technique to check for type "identicalness".
535
+ *
536
+ * It will check if the types are fully equal to each other.
537
+ * It will not fail if two objects have different values, but the same type.
538
+ * It will fail however if an object is missing a property.
539
+ *
540
+ * **_Unexpected failure_**? For a more permissive but less performant
541
+ * check that accommodates for equivalent intersection types,
542
+ * use {@linkcode PositiveExpectTypeOf.branded `.branded.toEqualTypeOf()`}.
543
+ * @see {@link https://github.com/mmkal/expect-type#why-is-my-assertion-failing The documentation for details}.
544
+ *
545
+ * @example
546
+ * <caption>Using generic type argument syntax</caption>
547
+ * ```ts
548
+ * expectTypeOf({ a: 1 }).toEqualTypeOf<{ a: number }>()
549
+ *
550
+ * expectTypeOf({ a: 1, b: 1 }).not.toEqualTypeOf<{ a: number }>()
551
+ * ```
552
+ *
553
+ * @example
554
+ * <caption>Using inferred type syntax by passing a value</caption>
555
+ * ```ts
556
+ * expectTypeOf({ a: 1 }).toEqualTypeOf({ a: 1 })
557
+ *
558
+ * expectTypeOf({ a: 1 }).toEqualTypeOf({ a: 2 })
559
+ * ```
560
+ *
561
+ * @param MISMATCH - The mismatch arguments.
562
+ * @returns `true`.
563
+ */
232
564
  <Expected>(...MISMATCH: MismatchArgs<StrictEqualUsingTSInternalIdenticalToOperator<Actual, Expected>, false>): true;
233
565
  };
234
566
  toMatchTypeOf: {
567
+ /**
568
+ * A less strict version of
569
+ * {@linkcode PositiveExpectTypeOf.toEqualTypeOf `.toEqualTypeOf()`}
570
+ * that allows for extra properties.
571
+ * This is roughly equivalent to an `extends` constraint
572
+ * in a function type argument.
573
+ *
574
+ * @example
575
+ * <caption>Using generic type argument syntax</caption>
576
+ * ```ts
577
+ * expectTypeOf({ a: 1, b: 1 }).toMatchTypeOf<{ a: number }>()
578
+ * ```
579
+ *
580
+ * @example
581
+ * <caption>Using inferred type syntax by passing a value</caption>
582
+ * ```ts
583
+ * expectTypeOf({ a: 1, b: 1 }).toMatchTypeOf({ a: 2 })
584
+ * ```
585
+ *
586
+ * @param value - The value to compare against the expected type.
587
+ * @param MISMATCH - The mismatch arguments.
588
+ * @returns `true`.
589
+ */
235
590
  <Expected>(value: Expected & AValue, // reason for `& AValue`: make sure this is only the selected overload when the end-user passes a value for an inferred typearg. The `Mismatch` type does match `AValue`.
236
591
  ...MISMATCH: MismatchArgs<Extends<Actual, Expected>, false>): true;
592
+ /**
593
+ * A less strict version of
594
+ * {@linkcode PositiveExpectTypeOf.toEqualTypeOf `.toEqualTypeOf()`}
595
+ * that allows for extra properties.
596
+ * This is roughly equivalent to an `extends` constraint
597
+ * in a function type argument.
598
+ *
599
+ * @example
600
+ * <caption>Using generic type argument syntax</caption>
601
+ * ```ts
602
+ * expectTypeOf({ a: 1, b: 1 }).toMatchTypeOf<{ a: number }>()
603
+ * ```
604
+ *
605
+ * @example
606
+ * <caption>Using inferred type syntax by passing a value</caption>
607
+ * ```ts
608
+ * expectTypeOf({ a: 1, b: 1 }).toMatchTypeOf({ a: 2 })
609
+ * ```
610
+ *
611
+ * @param MISMATCH - The mismatch arguments.
612
+ * @returns `true`.
613
+ */
237
614
  <Expected>(...MISMATCH: MismatchArgs<Extends<Actual, Expected>, false>): true;
238
615
  };
239
- toHaveProperty: <K extends string | number | symbol>(key: K, ...MISMATCH: MismatchArgs<Extends<K, keyof Actual>, false>) => true;
616
+ /**
617
+ * Checks whether an object has a given property.
618
+ *
619
+ * @example
620
+ * <caption>check that properties exist</caption>
621
+ * ```ts
622
+ * const obj = {a: 1, b: ''}
623
+ *
624
+ * expectTypeOf(obj).toHaveProperty('a')
625
+ *
626
+ * expectTypeOf(obj).not.toHaveProperty('c')
627
+ * ```
628
+ *
629
+ * @param key - The property key to check for.
630
+ * @param MISMATCH - The mismatch arguments.
631
+ * @returns `true`.
632
+ */
633
+ toHaveProperty: <KeyType extends string | number | symbol>(key: KeyType, ...MISMATCH: MismatchArgs<Extends<KeyType, keyof Actual>, false>) => true;
240
634
  }
635
+ /**
636
+ * Represents a conditional type that selects either
637
+ * {@linkcode PositiveExpectTypeOf} or {@linkcode NegativeExpectTypeOf} based
638
+ * on the value of the `positive` property in the {@linkcode Options} type.
639
+ */
241
640
  declare type ExpectTypeOf<Actual, Options extends {
242
641
  positive: boolean;
243
642
  }> = Options['positive'] extends true ? PositiveExpectTypeOf<Actual> : NegativeExpectTypeOf<Actual>;
643
+ /**
644
+ * Represents the base interface for the
645
+ * {@linkcode expectTypeOf()} function.
646
+ * Provides a set of assertion methods to perform type checks on a value.
647
+ */
244
648
  interface BaseExpectTypeOf<Actual, Options extends {
245
649
  positive: boolean;
246
650
  }> {
651
+ /**
652
+ * Checks whether the type of the value is `any`.
653
+ */
247
654
  toBeAny: Scolder<ExpectAny<Actual>, Options>;
655
+ /**
656
+ * Checks whether the type of the value is `unknown`.
657
+ */
248
658
  toBeUnknown: Scolder<ExpectUnknown<Actual>, Options>;
659
+ /**
660
+ * Checks whether the type of the value is `never`.
661
+ */
249
662
  toBeNever: Scolder<ExpectNever<Actual>, Options>;
663
+ /**
664
+ * Checks whether the type of the value is `function`.
665
+ */
250
666
  toBeFunction: Scolder<ExpectFunction<Actual>, Options>;
667
+ /**
668
+ * Checks whether the type of the value is `object`.
669
+ */
251
670
  toBeObject: Scolder<ExpectObject<Actual>, Options>;
671
+ /**
672
+ * Checks whether the type of the value is an {@linkcode Array}.
673
+ */
252
674
  toBeArray: Scolder<ExpectArray<Actual>, Options>;
675
+ /**
676
+ * Checks whether the type of the value is `number`.
677
+ */
253
678
  toBeNumber: Scolder<ExpectNumber<Actual>, Options>;
679
+ /**
680
+ * Checks whether the type of the value is `string`.
681
+ */
254
682
  toBeString: Scolder<ExpectString<Actual>, Options>;
683
+ /**
684
+ * Checks whether the type of the value is `boolean`.
685
+ */
255
686
  toBeBoolean: Scolder<ExpectBoolean<Actual>, Options>;
687
+ /**
688
+ * Checks whether the type of the value is `void`.
689
+ */
256
690
  toBeVoid: Scolder<ExpectVoid<Actual>, Options>;
691
+ /**
692
+ * Checks whether the type of the value is `symbol`.
693
+ */
257
694
  toBeSymbol: Scolder<ExpectSymbol<Actual>, Options>;
695
+ /**
696
+ * Checks whether the type of the value is `null`.
697
+ */
258
698
  toBeNull: Scolder<ExpectNull<Actual>, Options>;
699
+ /**
700
+ * Checks whether the type of the value is `undefined`.
701
+ */
259
702
  toBeUndefined: Scolder<ExpectUndefined<Actual>, Options>;
703
+ /**
704
+ * Checks whether the type of the value is `null` or `undefined`.
705
+ */
260
706
  toBeNullable: Scolder<ExpectNullable<Actual>, Options>;
707
+ /**
708
+ * Checks whether a function is callable with the given parameters.
709
+ *
710
+ * __Note__: You cannot negate this assertion with
711
+ * {@linkcode PositiveExpectTypeOf.not `.not`} you need to use
712
+ * `ts-expect-error` instead.
713
+ *
714
+ * @example
715
+ * ```ts
716
+ * const f = (a: number) => [a, a]
717
+ *
718
+ * expectTypeOf(f).toBeCallableWith(1)
719
+ * ```
720
+ *
721
+ * __Known Limitation__: This assertion will likely fail if you try to use it
722
+ * with a generic function or an overload.
723
+ * @see {@link https://github.com/mmkal/expect-type/issues/50 This issue} for an example and a workaround.
724
+ *
725
+ * @param args - The arguments to check for callability.
726
+ * @returns `true`.
727
+ */
261
728
  toBeCallableWith: Options['positive'] extends true ? (...args: Params<Actual>) => true : never;
729
+ /**
730
+ * Checks whether a class is constructible with the given parameters.
731
+ *
732
+ * @example
733
+ * ```ts
734
+ * expectTypeOf(Date).toBeConstructibleWith('1970')
735
+ *
736
+ * expectTypeOf(Date).toBeConstructibleWith(0)
737
+ *
738
+ * expectTypeOf(Date).toBeConstructibleWith(new Date())
739
+ *
740
+ * expectTypeOf(Date).toBeConstructibleWith()
741
+ * ```
742
+ *
743
+ * @param args - The arguments to check for constructibility.
744
+ * @returns `true`.
745
+ */
262
746
  toBeConstructibleWith: Options['positive'] extends true ? (...args: ConstructorParams<Actual>) => true : never;
747
+ /**
748
+ * Equivalent to the {@linkcode Extract} utility type.
749
+ * Helps narrow down complex union types.
750
+ *
751
+ * @example
752
+ * ```ts
753
+ * type ResponsiveProp<T> = T | T[] | { xs?: T; sm?: T; md?: T }
754
+ *
755
+ * interface CSSProperties {
756
+ * margin?: string
757
+ * padding?: string
758
+ * }
759
+ *
760
+ * function getResponsiveProp<T>(_props: T): ResponsiveProp<T> {
761
+ * return {}
762
+ * }
763
+ *
764
+ * const cssProperties: CSSProperties = { margin: '1px', padding: '2px' }
765
+ *
766
+ * expectTypeOf(getResponsiveProp(cssProperties))
767
+ * .extract<{ xs?: any }>() // extracts the last type from a union
768
+ * .toEqualTypeOf<{
769
+ * xs?: CSSProperties
770
+ * sm?: CSSProperties
771
+ * md?: CSSProperties
772
+ * }>()
773
+ *
774
+ * expectTypeOf(getResponsiveProp(cssProperties))
775
+ * .extract<unknown[]>() // extracts an array from a union
776
+ * .toEqualTypeOf<CSSProperties[]>()
777
+ * ```
778
+ *
779
+ * __Note__: If no type is found in the union, it will return `never`.
780
+ *
781
+ * @param v - The type to extract from the union.
782
+ * @returns The type after extracting the type from the union.
783
+ */
263
784
  extract: <V>(v?: V) => ExpectTypeOf<Extract<Actual, V>, Options>;
785
+ /**
786
+ * Equivalent to the {@linkcode Exclude} utility type.
787
+ * Removes types from a union.
788
+ *
789
+ * @example
790
+ * ```ts
791
+ * type ResponsiveProp<T> = T | T[] | { xs?: T; sm?: T; md?: T }
792
+ *
793
+ * interface CSSProperties {
794
+ * margin?: string
795
+ * padding?: string
796
+ * }
797
+ *
798
+ * function getResponsiveProp<T>(_props: T): ResponsiveProp<T> {
799
+ * return {}
800
+ * }
801
+ *
802
+ * const cssProperties: CSSProperties = { margin: '1px', padding: '2px' }
803
+ *
804
+ * expectTypeOf(getResponsiveProp(cssProperties))
805
+ * .exclude<unknown[]>()
806
+ * .exclude<{ xs?: unknown }>() // or just `.exclude<unknown[] | { xs?: unknown }>()`
807
+ * .toEqualTypeOf<CSSProperties>()
808
+ * ```
809
+ */
264
810
  exclude: <V>(v?: V) => ExpectTypeOf<Exclude<Actual, V>, Options>;
265
- parameter: <K extends keyof Params<Actual>>(number: K) => ExpectTypeOf<Params<Actual>[K], Options>;
811
+ /**
812
+ * Equivalent to the {@linkcode Pick} utility type.
813
+ * Helps select a subset of properties from an object type.
814
+ *
815
+ * @example
816
+ * ```ts
817
+ * interface Person {
818
+ * name: string
819
+ * age: number
820
+ * }
821
+ *
822
+ * expectTypeOf<Person>()
823
+ * .pick<'name'>()
824
+ * .toEqualTypeOf<{ name: string }>()
825
+ * ```
826
+ *
827
+ * @param keyToPick - The property key to pick.
828
+ * @returns The type after picking the property.
829
+ */
830
+ pick: <KeyToPick extends keyof Actual>(keyToPick?: KeyToPick) => ExpectTypeOf<Pick<Actual, KeyToPick>, Options>;
831
+ /**
832
+ * Equivalent to the {@linkcode Omit} utility type.
833
+ * Helps remove a subset of properties from an object type.
834
+ *
835
+ * @example
836
+ * ```ts
837
+ * interface Person {
838
+ * name: string
839
+ * age: number
840
+ * }
841
+ *
842
+ * expectTypeOf<Person>().omit<'name'>().toEqualTypeOf<{ age: number }>()
843
+ * ```
844
+ *
845
+ * @param keyToOmit - The property key to omit.
846
+ * @returns The type after omitting the property.
847
+ */
848
+ omit: <KeyToOmit extends keyof Actual | (PropertyKey & Record<never, never>)>(keyToOmit?: KeyToOmit) => ExpectTypeOf<Omit<Actual, KeyToOmit>, Options>;
849
+ /**
850
+ * Extracts a certain function argument with `.parameter(number)` call to
851
+ * perform other assertions on it.
852
+ *
853
+ * @example
854
+ * ```ts
855
+ * function foo(a: number, b: string) {
856
+ * return [a, b]
857
+ * }
858
+ *
859
+ * expectTypeOf(foo).parameter(0).toBeNumber()
860
+ *
861
+ * expectTypeOf(foo).parameter(1).toBeString()
862
+ * ```
863
+ *
864
+ * @param index - The index of the parameter to extract.
865
+ * @returns The extracted parameter type.
866
+ */
867
+ parameter: <Index extends keyof Params<Actual>>(index: Index) => ExpectTypeOf<Params<Actual>[Index], Options>;
868
+ /**
869
+ * Equivalent to the {@linkcode Parameters} utility type.
870
+ * Extracts function parameters to perform assertions on its value.
871
+ * Parameters are returned as an array.
872
+ *
873
+ * @example
874
+ * ```ts
875
+ * function noParam() {}
876
+ *
877
+ * function hasParam(s: string) {}
878
+ *
879
+ * expectTypeOf(noParam).parameters.toEqualTypeOf<[]>()
880
+ *
881
+ * expectTypeOf(hasParam).parameters.toEqualTypeOf<[string]>()
882
+ * ```
883
+ */
266
884
  parameters: ExpectTypeOf<Params<Actual>, Options>;
885
+ /**
886
+ * Equivalent to the {@linkcode ConstructorParameters} utility type.
887
+ * Extracts constructor parameters as an array of values and
888
+ * perform assertions on them with this method.
889
+ *
890
+ * @example
891
+ * ```ts
892
+ * expectTypeOf(Date).constructorParameters.toEqualTypeOf<
893
+ * [] | [string | number | Date]
894
+ * >()
895
+ * ```
896
+ */
267
897
  constructorParameters: ExpectTypeOf<ConstructorParams<Actual>, Options>;
898
+ /**
899
+ * Equivalent to the {@linkcode ThisParameterType} utility type.
900
+ * Extracts the `this` parameter of a function to
901
+ * perform assertions on its value.
902
+ *
903
+ * @example
904
+ * ```ts
905
+ * function greet(this: { name: string }, message: string) {
906
+ * return `Hello ${this.name}, here's your message: ${message}`
907
+ * }
908
+ *
909
+ * expectTypeOf(greet).thisParameter.toEqualTypeOf<{ name: string }>()
910
+ * ```
911
+ */
268
912
  thisParameter: ExpectTypeOf<ThisParameterType<Actual>, Options>;
913
+ /**
914
+ * Equivalent to the {@linkcode InstanceType} utility type.
915
+ * Extracts the instance type of a class to perform assertions on.
916
+ *
917
+ * @example
918
+ * ```ts
919
+ * expectTypeOf(Date).instance.toHaveProperty('toISOString')
920
+ * ```
921
+ */
269
922
  instance: Actual extends new (...args: any[]) => infer I ? ExpectTypeOf<I, Options> : never;
923
+ /**
924
+ * Equivalent to the {@linkcode ReturnType} utility type.
925
+ * Extracts the return type of a function.
926
+ *
927
+ * @example
928
+ * ```ts
929
+ * expectTypeOf(() => {}).returns.toBeVoid()
930
+ *
931
+ * expectTypeOf((a: number) => [a, a]).returns.toEqualTypeOf([1, 2])
932
+ * ```
933
+ */
270
934
  returns: Actual extends (...args: any[]) => infer R ? ExpectTypeOf<R, Options> : never;
271
- resolves: Actual extends PromiseLike<infer R> ? ExpectTypeOf<R, Options> : never;
272
- items: Actual extends ArrayLike<infer R> ? ExpectTypeOf<R, Options> : never;
935
+ /**
936
+ * Extracts resolved value of a Promise,
937
+ * so you can perform other assertions on it.
938
+ *
939
+ * @example
940
+ * ```ts
941
+ * async function asyncFunc() {
942
+ * return 123
943
+ * }
944
+ *
945
+ * expectTypeOf(asyncFunc).returns.resolves.toBeNumber()
946
+ *
947
+ * expectTypeOf(Promise.resolve('string')).resolves.toBeString()
948
+ * ```
949
+ *
950
+ * Type Equivalent:
951
+ * ```ts
952
+ * type Resolves<PromiseType> = PromiseType extends PromiseLike<infer ResolvedType>
953
+ * ? ResolvedType
954
+ * : never
955
+ * ```
956
+ */
957
+ resolves: Actual extends PromiseLike<infer ResolvedType> ? ExpectTypeOf<ResolvedType, Options> : never;
958
+ /**
959
+ * Extracts array item type to perform assertions on.
960
+ *
961
+ * @example
962
+ * ```ts
963
+ * expectTypeOf([1, 2, 3]).items.toEqualTypeOf<number>()
964
+ *
965
+ * expectTypeOf([1, 2, 3]).items.not.toEqualTypeOf<string>()
966
+ * ```
967
+ *
968
+ * __Type Equivalent__:
969
+ * ```ts
970
+ * type Items<ArrayType> = ArrayType extends ArrayLike<infer ItemType>
971
+ * ? ItemType
972
+ * : never
973
+ * ```
974
+ */
975
+ items: Actual extends ArrayLike<infer ItemType> ? ExpectTypeOf<ItemType, Options> : never;
976
+ /**
977
+ * Extracts the type guarded by a function to perform assertions on.
978
+ *
979
+ * @example
980
+ * ```ts
981
+ * function isString(v: any): v is string {
982
+ * return typeof v === 'string'
983
+ * }
984
+ *
985
+ * expectTypeOf(isString).guards.toBeString()
986
+ * ```
987
+ */
273
988
  guards: Actual extends (v: any, ...args: any[]) => v is infer T ? ExpectTypeOf<T, Options> : never;
989
+ /**
990
+ * Extracts the type asserted by a function to perform assertions on.
991
+ *
992
+ * @example
993
+ * ```ts
994
+ * function assertNumber(v: any): asserts v is number {
995
+ * if (typeof v !== 'number')
996
+ * throw new TypeError('Nope !')
997
+ * }
998
+ *
999
+ * expectTypeOf(assertNumber).asserts.toBeNumber()
1000
+ * ```
1001
+ */
274
1002
  asserts: Actual extends (v: any, ...args: any[]) => asserts v is infer T ? unknown extends T ? never : ExpectTypeOf<T, Options> : never;
275
1003
  }
1004
+ /**
1005
+ * Represents a function that allows asserting the expected type of a value.
1006
+ */
276
1007
  declare type _ExpectTypeOf = {
1008
+ /**
1009
+ * Asserts the expected type of a value.
1010
+ *
1011
+ * @param actual - The actual value being asserted.
1012
+ * @returns An object representing the expected type assertion.
1013
+ */
277
1014
  <Actual>(actual: Actual): ExpectTypeOf<Actual, {
278
1015
  positive: true;
279
1016
  branded: false;
280
1017
  }>;
1018
+ /**
1019
+ * Asserts the expected type of a value without providing an actual value.
1020
+ *
1021
+ * @returns An object representing the expected type assertion.
1022
+ */
281
1023
  <Actual>(): ExpectTypeOf<Actual, {
282
1024
  positive: true;
283
1025
  branded: false;
@@ -312,6 +1054,11 @@ interface AssertType {
312
1054
  }
313
1055
  declare const assertType: AssertType;
314
1056
 
1057
+ interface BrowserUI {
1058
+ setCurrentFileId: (fileId: string) => void;
1059
+ setIframeViewport: (width: number, height: number) => Promise<void>;
1060
+ }
1061
+
315
1062
  /**
316
1063
  * This utils allows computational intensive tasks to only be ran once
317
1064
  * across test reruns to improve the watch mode performance.
@@ -519,14 +1266,16 @@ interface VitestUtils {
519
1266
  * @param path Path to the module. Can be aliased, if your Vitest config supports it
520
1267
  * @param factory Mocked module factory. The result of this function will be an exports object
521
1268
  */
522
- mock: (path: string, factory?: MockFactoryWithHelper) => void;
1269
+ mock(path: string, factory?: MockFactoryWithHelper): void;
1270
+ mock<T>(module: Promise<T>, factory?: MockFactoryWithHelper<T>): void;
523
1271
  /**
524
1272
  * Removes module from mocked registry. All calls to import will return the original module even if it was mocked before.
525
1273
  *
526
1274
  * This call is hoisted to the top of the file, so it will only unmock modules that were defined in `setupFiles`, for example.
527
1275
  * @param path Path to the module. Can be aliased, if your Vitest config supports it
528
1276
  */
529
- unmock: (path: string) => void;
1277
+ unmock(path: string): void;
1278
+ unmock(module: Promise<unknown>): void;
530
1279
  /**
531
1280
  * Mocks every subsequent [dynamic import](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) call.
532
1281
  *
@@ -536,14 +1285,16 @@ interface VitestUtils {
536
1285
  * @param path Path to the module. Can be aliased, if your Vitest config supports it
537
1286
  * @param factory Mocked module factory. The result of this function will be an exports object
538
1287
  */
539
- doMock: (path: string, factory?: MockFactoryWithHelper) => void;
1288
+ doMock(path: string, factory?: MockFactoryWithHelper): void;
1289
+ doMock<T>(module: Promise<T>, factory?: MockFactoryWithHelper<T>): void;
540
1290
  /**
541
1291
  * Removes module from mocked registry. All subsequent calls to import will return original module.
542
1292
  *
543
1293
  * Unlike [`vi.unmock`](https://vitest.dev/api/vi#vi-unmock), this method is not hoisted to the top of the file.
544
1294
  * @param path Path to the module. Can be aliased, if your Vitest config supports it
545
1295
  */
546
- doUnmock: (path: string) => void;
1296
+ doUnmock(path: string): void;
1297
+ doUnmock(module: Promise<unknown>): void;
547
1298
  /**
548
1299
  * Imports module, bypassing all checks if it should be mocked.
549
1300
  * Can be useful if you want to mock module partially.
@@ -671,43 +1422,4 @@ declare function isWatchMode(): boolean;
671
1422
  */
672
1423
  declare function inject<T extends keyof ProvidedContext>(key: T): ProvidedContext[T];
673
1424
 
674
- interface TransformResultWithSource extends TransformResult {
675
- source?: string;
676
- }
677
- interface WebSocketHandlers {
678
- onUnhandledError: (error: unknown, type: string) => Promise<void>;
679
- onCollected: (files?: File[]) => Promise<void>;
680
- onTaskUpdate: (packs: TaskResultPack[]) => void;
681
- onAfterSuiteRun: (meta: AfterSuiteRunMeta) => void;
682
- onCancel: (reason: CancelReason) => void;
683
- getCountOfFailedTests: () => number;
684
- sendLog: (log: UserConsoleLog) => void;
685
- getFiles: () => File[];
686
- getTestFiles: () => Promise<[name: string, file: string][]>;
687
- getPaths: () => string[];
688
- getConfig: () => ResolvedConfig;
689
- resolveSnapshotPath: (testPath: string) => string;
690
- resolveSnapshotRawPath: (testPath: string, rawPath: string) => string;
691
- getModuleGraph: (id: string) => Promise<ModuleGraphData>;
692
- getBrowserFileSourceMap: (id: string) => Promise<TransformResult['map'] | undefined>;
693
- getTransformResult: (id: string) => Promise<TransformResultWithSource | undefined>;
694
- readSnapshotFile: (id: string) => Promise<string | null>;
695
- readTestFile: (id: string) => Promise<string | null>;
696
- saveTestFile: (id: string, content: string) => Promise<void>;
697
- saveSnapshotFile: (id: string, content: string) => Promise<void>;
698
- removeSnapshotFile: (id: string) => Promise<void>;
699
- snapshotSaved: (snapshot: SnapshotResult) => void;
700
- rerun: (files: string[]) => Promise<void>;
701
- updateSnapshot: (file?: File) => Promise<void>;
702
- getProvidedContext: () => ProvidedContext;
703
- getUnhandledErrors: () => unknown[];
704
- finishBrowserTests: () => void;
705
- getBrowserFiles: () => string[];
706
- debug: (...args: string[]) => void;
707
- }
708
- interface WebSocketEvents extends Pick<Reporter, 'onCollected' | 'onFinished' | 'onTaskUpdate' | 'onUserConsoleLog' | 'onPathsCollected'> {
709
- onCancel: (reason: CancelReason) => void;
710
- onFinishedReportCoverage: () => void;
711
- }
712
-
713
- export { AfterSuiteRunMeta, type AssertType, type ExpectTypeOf, ModuleGraphData, ProvidedContext, Reporter, ResolvedConfig, RuntimeConfig, type TransformResultWithSource, UserConsoleLog, type VitestUtils, type WebSocketEvents, type WebSocketHandlers, assertType, createExpect, globalExpect as expect, expectTypeOf, getRunningMode, inject, isFirstRun, isWatchMode, runOnce, vi, vitest };
1425
+ export { type AssertType, type BrowserUI, type ExpectTypeOf, ProvidedContext, RuntimeConfig, type VitestUtils, assertType, createExpect, globalExpect as expect, expectTypeOf, getRunningMode, inject, isFirstRun, isWatchMode, runOnce, vi, vitest };