Skip to content

fix(types)!: the helper types are not global, only the ExpectWebdriverIO namespace and 2 WebdriverIO aliases - #2385

Merged
plum117 merged 1 commit into
webdriverio:mainfrom
plum117:v8/global-helper-types
Oct 10, 2026
Merged

plum117 merged 1 commit into
webdriverio:mainfrom
plum117:v8/global-helper-types

Conversation

@plum117

@plum117 plum117 commented Oct 10, 2026 •

Copy link
Copy Markdown
Collaborator

Proposed changes

The types file of v7 (types/expect-webdriverio.d.ts) was a global script: no import and no export, so its 73 top-level helper types were global names. v8 kept 70 of them in declare global (Test, TestResult, Scenario, MaybeArray, MultiRemoteValues, AsymmetricMatcher, WdioCustomMatchers…). The docs never named them: the public types are the ExpectWebdriverIO namespace and, since #2338, its named exports.

A project with its own global type of the same name failed, and could not fix it:

declare global {
    type Test = { id: number, name: string }   // error TS2300: Duplicate identifier 'Test'.
}

Decision of the maintainer (option B of the analysis): before 8.0.0, only the ExpectWebdriverIO namespace and 2 aliases of WebdriverIO types stay global.

  • The 68 helper types move out of declare global, to the module scope of src/publicTypes/expectWebdriverIO.ts. The namespace still uses them. They are exported for src/ (25 files import them now), and the entry points do not export them: src/index.ts exports only the listed namespace types, and the exports map of the package has no path to this file.
  • ChainablePromiseElement and ChainablePromiseArray stay global: they are the webdriverio types 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.ts writes out WdioElementOrPromiseLike with 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.Test of @wdio/types, the types of expect, 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 uses Matchers<R> and PartialMatcher with no type argument; with our types it fails with TS2428: All declarations of 'Matchers' must have identical type parameters and TS2314: Generic type 'PartialMatcher' requires 1 type argument(s);
  • a matcher for any value (R), an async matcher for elements only (Promise<R>, never on other values), the asymmetric form;
  • declare global in a module file, declare namespace in a global .d.ts; which names are public; the expect module and jest namespace for Jest.

docs/Types.md links it, and the migration guide has the new section "The helper types are not global".

How you tested

  • Type tests, in test-types/mocha/mocha.test-d.ts (failed before):
    • ChainablePromiseElement and ChainablePromiseArray are global, and equal the types of webdriverio;
    • a project can declare its own global Test, MaybeArray and AsymmetricMatcher (before: Duplicate identifier);
    • the 65 other helper types are not global: one @ts-expect-error each, with never as each type argument (a check compiles the 65 with never when they are visible, so each line fails only because of the name);
    • the example of docs/CustomMatchers.md: a matcher for any value, an element matcher that is never on a string, the asymmetric form.
  • The 6 lines of the type tests that used WdioCustomMatchers, ExpectLibInverse and WdioSome as globals use public types now (ExpectWebdriverIO.Matchers, Inverse of expect, { readonly elements: T }).
  • The examples of the migration guide, compiled against the new lib/: the "after" code compiles; the old code fails with Cannot find name for MaybeArray, Test, TestResult and MultiRemoteValues, not for ChainablePromiseElement.
  • 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

  • What they use from us: a search of the type files of @wdio/globals, @wdio/jasmine-framework, @wdio/runner, @wdio/visual-service, and of @wdio/cucumber-framework 10.0.1 and @wdio/mocha-framework 10.0.1 (downloaded), for the 68 helper names: none uses them. They use only ExpectWebdriverIO.Expect, ExpectWebdriverIO.Matchers, ExpectWebdriverIO.PartialMatcher<number>, and the named exports Expect, expect, wdioCustomMatchers and getDefaultOptions, which do not change. Cucumber imports PickleStep and Pickle from @cucumber/messages; Mocha does not reference expect-webdriverio.
  • Playgrounds: the type checks of mocha, jasmine (with @wdio/jasmine-framework types), jest and browser-runner pass. With skipLibCheck: 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.
  • Cucumber (no playground): a project with the packed package, @wdio/cucumber-framework 10.0.1, @wdio/globals 10.0.2 and @cucumber/cucumber 13.3.0 (installed with --ignore-scripts): step definitions with our matchers, the custom matcher of the docs (with its never check), wdio.conf.ts with beforeStep and afterScenario, and a global Test of the project. With skipLibCheck: true, no error. With false: 19 errors after, all in other libraries; 21 before, the 2 more are Duplicate identifier 'Test' (the project's type against ours).

🤖 Generated with Claude Code

…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
plum117 marked this pull request as ready for review October 10, 2026 15:04
@greptile-apps

greptile-apps Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerConfidence Score: 5/5

[High impact] The PR appears safe to merge with the documented TypeScript breaking change.

Summary

Moves helper types into module scope while keeping ExpectWebdriverIO, ChainablePromiseElement, and ChainablePromiseArray global.

  • TypeScript projects can now use their own helper type names.
  • Custom matcher docs show how to add TypeScript types.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  H["Module-scoped helper types"] --> N["Global ExpectWebdriverIO namespace"]
  H --> I["Internal type imports"]
  N --> E["Named public types"]
  N --> J["Jest matchers"]
  N --> A["Jasmine async matchers"]
  C["Two global chainable aliases"] --> N
Loading

Reviews (1) · Last reviewed commit: "fix(types)!: the helper types are not gl..." · Reviewed by Greptile

@plum117
plum117 merged commit 4347247 into webdriverio:main Oct 10, 2026
11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant