Repository navigation
fix(types)!: the helper types are not global, only the ExpectWebdriverIO namespace and 2 WebdriverIO aliases - #2385
Merged
Conversation
…rIO namespace and 2 WebdriverIO aliases The types file of v7 was a global script, so its 70 helper types were global names (`Test`, `TestResult`, `MaybeArray`, `AsymmetricMatcher`…), and a project with its own global type of the same name failed with `Duplicate identifier`. They move out of `declare global`, to the module scope of `src/publicTypes/expectWebdriverIO.ts`; `src/` imports them, and the entry points do not export them. `ChainablePromiseElement` and `ChainablePromiseArray` stay global: custom matcher types use them. The docs explain how to type a custom matcher: `Matchers<R, T>` with both type parameters, `PartialMatcher<T>`, a matcher for elements only; the example is a type test. BREAKING CHANGE: a file that uses a helper type as a global name, e.g. `Test` or `MaybeArray`, fails with `Cannot find name`: use the public type (`Frameworks.Test` of `@wdio/types`, `ExpectWebdriverIO.*`) or write it. See the migration guide. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
plum117
marked this pull request as ready for review
October 10, 2026 15:04
Contributor
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Proposed changes
The types file of v7 (
types/expect-webdriverio.d.ts) was a global script: noimportand noexport, so its 73 top-level helper types were global names. v8 kept 70 of them indeclare global(Test,TestResult,Scenario,MaybeArray,MultiRemoteValues,AsymmetricMatcher,WdioCustomMatchers…). The docs never named them: the public types are theExpectWebdriverIOnamespace and, since #2338, its named exports.A project with its own global type of the same name failed, and could not fix it:
Decision of the maintainer (option B of the analysis): before 8.0.0, only the
ExpectWebdriverIOnamespace and 2 aliases of WebdriverIO types stay global.declare global, to the module scope ofsrc/publicTypes/expectWebdriverIO.ts. The namespace still uses them. They are exported forsrc/(25 files import them now), and the entry points do not export them:src/index.tsexports only the listed namespace types, and theexportsmap of the package has no path to this file.ChainablePromiseElementandChainablePromiseArraystay global: they are thewebdriveriotypes of a not-awaited$()and$$(), and custom matcher types use them (our own type tests do). WebdriverIO exports them from its module only, not as global names.jest.d.tswrites outWdioElementOrPromiseLikewith global names.Breaking for TypeScript only (no change at run time): a file that writes a helper type as a global name fails with
Cannot find name. The migration guide has a table of replacements (Frameworks.Testof@wdio/types, the types ofexpect,ExpectWebdriverIO.*).Docs of the custom matcher types (
docs/CustomMatchers.md, "TypeScript"): one example that the type tests check (customMatchers-docs-example.ts), for any framework:Matchers<R, T>with both type parameters. The example of webdriver.io/docs/custommatchers usesMatchers<R>andPartialMatcherwith no type argument; with our types it fails withTS2428: All declarations of 'Matchers' must have identical type parametersandTS2314: Generic type 'PartialMatcher' requires 1 type argument(s);R), an async matcher for elements only (Promise<R>,neveron other values), the asymmetric form;declare globalin a module file,declare namespacein a global.d.ts; which names are public; theexpectmodule andjestnamespace for Jest.docs/Types.mdlinks it, and the migration guide has the new section "The helper types are not global".How you tested
test-types/mocha/mocha.test-d.ts(failed before):ChainablePromiseElementandChainablePromiseArrayare global, and equal the types ofwebdriverio;Test,MaybeArrayandAsymmetricMatcher(before:Duplicate identifier);@ts-expect-erroreach, withneveras each type argument (a check compiles the 65 withneverwhen they are visible, so each line fails only because of the name);docs/CustomMatchers.md: a matcher for any value, an element matcher that isneveron a string, the asymmetric form.WdioCustomMatchers,ExpectLibInverseandWdioSomeas globals use public types now (ExpectWebdriverIO.Matchers,Inverseofexpect,{ readonly elements: T }).lib/: the "after" code compiles; the old code fails withCannot find nameforMaybeArray,Test,TestResultandMultiRemoteValues, not forChainablePromiseElement.pnpm test: lint, tsc, 3537 unit tests, the type tests (Mocha 152, Jest 73, Jasmine 43), the 12 declaration checks, and the packed package in a clean project (module, expect-global, jest, jasmine). The Mocha playground type check and lint. The multi-remote naming check, and the links of the 3 changed docs.The WebdriverIO frameworks still get what they need
@wdio/globals,@wdio/jasmine-framework,@wdio/runner,@wdio/visual-service, and of@wdio/cucumber-framework10.0.1 and@wdio/mocha-framework10.0.1 (downloaded), for the 68 helper names: none uses them. They use onlyExpectWebdriverIO.Expect,ExpectWebdriverIO.Matchers,ExpectWebdriverIO.PartialMatcher<number>, and the named exportsExpect,expect,wdioCustomMatchersandgetDefaultOptions, which do not change. Cucumber importsPickleStepandPicklefrom@cucumber/messages; Mocha does not reference expect-webdriverio.mocha,jasmine(with@wdio/jasmine-frameworktypes),jestandbrowser-runnerpass. WithskipLibCheck: false, the errors of the libraries (@wdio/globals,@types/node…) are the same before and after: jasmine 19, mocha 19, jest 15, and the diff is empty.@wdio/cucumber-framework10.0.1,@wdio/globals10.0.2 and@cucumber/cucumber13.3.0 (installed with--ignore-scripts): step definitions with our matchers, the custom matcher of the docs (with itsnevercheck),wdio.conf.tswithbeforeStepandafterScenario, and a globalTestof the project. WithskipLibCheck: true, no error. Withfalse: 19 errors after, all in other libraries; 21 before, the 2 more areDuplicate identifier 'Test'(the project's type against ours).🤖 Generated with Claude Code