fix: typescript sync mode compilation

Importing the webdriverio package directly also declares async types for
browser APIs - this was missed due to sync mode tests using javascript
to avoid conflicts with the global declarations of command types.

To fix compilation of sync mode projects the types for the methods used
by the lib are manually defined instead of using WebdriverIO types
directly. In order to ensure the WebdriverIO.Element type the queries
return is correct a WebdriverIO namespace with an empty Element
interface is declared; the queries return this empty interface so that
the end user can hydrate the interface with the correct types for the
mode of WebdriverIO they are using.

BREAKING CHANGE: users will now need to include WebdriverIO types in
their tsconfig.json in order to hydrate the WebdriverIO.Element type.

In order to verify the lib compiles for both async and sync mode
projects the test folder has been reorganised into two sets of tests:
those that use async mode and those that use sync mode. To achieve this
a tsconfig is included in each directory that includes the corresponding
WebdriverIO types for their mode. In order to verify each test mode
compiles correctly `typecheck` npm scripts have been added and are used
in the validate script.

Author: olivierwilkinson

.eslintrc

@@ -13,6 +13,8 @@
     "testing-library/no-await-sync-query": "off",
     "testing-library/no-dom-import": "off",
     "testing-library/prefer-screen-queries": "off",
+    "no-undef": "off",
+    "no-use-before-define": "off",
     "no-unused-vars": "off",
     "@typescript-eslint/no-unused-vars": ["error"]
   },

package.json

@@ -9,9 +9,13 @@
     "build": "tsc -p tsconfig.build.json",
     "lint": "kcd-scripts lint",
     "test:unit": "kcd-scripts test --no-watch --config=jest.config.js",
-    "validate": "kcd-scripts validate build,lint,test",
+    "validate": "kcd-scripts validate build,lint,test,typecheck",
     "test": "wdio wdio.conf.js",
-    "semantic-release": "semantic-release"
+    "semantic-release": "semantic-release",
+    "typecheck:async": "tsc -p ./test/async/tsconfig.json",
+    "typecheck:sync": "tsc -p ./test/sync/tsconfig.json",
+    "typecheck:build": "npm run build -- --noEmit",
+    "typecheck": "npm-run-all typecheck:build typecheck:**"
   },
   "files": [
     "dist"
@@ -38,6 +42,7 @@
     "chromedriver": "^89.0.0",
     "eslint": "^7.6.0",
     "kcd-scripts": "^5.0.0",
+    "npm-run-all": "^4.1.5",
     "semantic-release": "^17.0.2",
     "ts-node": "^9.1.1",
     "typescript": "^4.1.3",

src/index.ts

@@ -3,9 +3,14 @@
 import path from 'path'
 import fs from 'fs'
 import {queries as baseQueries} from '@testing-library/dom'
-import {Element, BrowserObject, MultiRemoteBrowserObject} from 'webdriverio'
 
-import {Config, QueryName, WebdriverIOQueries} from './types'
+import {
+  BrowserBase,
+  Config,
+  ElementBase,
+  QueryName,
+  WebdriverIOQueries,
+} from './types'
 
 declare global {
   interface Window {
@@ -26,7 +31,7 @@ const DOM_TESTING_LIBRARY_UMD = fs
 
 let _config: Partial<Config>
 
-async function injectDOMTestingLibrary(container: Element) {
+async function injectDOMTestingLibrary(container: ElementBase) {
   const shouldInject = await container.execute(function () {
     return !window.TestingLibraryDom
   })
@@ -108,18 +113,18 @@ Element. There are valid WebElement JSONs that exclude the key but can be turned
 into Elements, such as { ELEMENT: elementId }; this can happen in setups that
 aren't generated by @wdio/cli.
 */
-function createElement(container: Element, elementValue: any) {
+function createElement(container: ElementBase, elementValue: any) {
   return container.$({
     'element-6066-11e4-a52e-4f735466cecf': '',
     ...elementValue,
   })
 }
 
-function createQuery(element: Element, queryName: string) {
+function createQuery(element: ElementBase, queryName: string) {
   return async (...args: any[]) => {
     await injectDOMTestingLibrary(element)
 
-    const result = await element.executeAsync<any[], any[]>(executeQuery, [
+    const result = await element.executeAsync(executeQuery, [
       queryName,
       element,
       ...args.map(serializeArg),
@@ -141,7 +146,7 @@ function createQuery(element: Element, queryName: string) {
   }
 }
 
-function within(element: Element) {
+function within(element: ElementBase) {
   return Object.keys(baseQueries).reduce(
     (queries, queryName) => ({
       ...queries,
@@ -151,7 +156,7 @@ function within(element: Element) {
   ) as WebdriverIOQueries
 }
 
-function setupBrowser(browser: BrowserObject | MultiRemoteBrowserObject) {
+function setupBrowser(browser: BrowserBase) {
   const queries: {[key: string]: any} = {}
 
   Object.keys(baseQueries).forEach((key) => {
@@ -171,9 +176,8 @@ function setupBrowser(browser: BrowserObject | MultiRemoteBrowserObject) {
     // add query to Elements
     browser.addCommand(
       queryName,
-      function (...args: any[]) {
-        const element = this as Element
-        return within(element)[queryName](...args)
+      function (this, ...args) {
+        return within(this)[queryName](...args)
       },
       true,
     )

src/types.ts

@@ -3,7 +3,45 @@ import {
   BoundFunction as BoundFunctionBase,
   queries,
 } from '@testing-library/dom'
-import {Element} from 'webdriverio'
+
+declare global {
+  namespace WebdriverIO {
+    interface Element extends ElementBase {}
+  }
+}
+
+export type ElementBase = {
+  $(
+    selector: string | object,
+  ): WebdriverIO.Element | Promise<WebdriverIO.Element>
+
+  execute<T>(
+    script: string | ((...args: any[]) => T),
+    ...args: any[]
+  ): Promise<T>
+
+  execute<T>(
+    script: string | ((...args: any[]) => T),
+    ...args: any[]
+  ): T
+
+  executeAsync(script: string | ((...args: any[]) => void), ...args: any[]): any
+}
+
+export type BrowserBase = {
+  $(
+    selector: string | object,
+  ): WebdriverIO.Element | Promise<WebdriverIO.Element>
+
+  addCommand<T extends boolean>(
+    queryName: string,
+    commandFn: (
+      this: T extends true ? ElementBase : BrowserBase,
+      ...args: any[]
+    ) => void,
+    isElementCommand?: T,
+  ): any
+}
 
 export type Config = Pick<
   BaseConfig,
@@ -15,13 +53,13 @@ export type Config = Pick<
 >
 
 export type WebdriverIOQueryReturnType<T> = T extends Promise<HTMLElement>
-  ? Element
+  ? WebdriverIO.Element
   : T extends HTMLElement
-  ? Element
+  ? WebdriverIO.Element
   : T extends Promise<HTMLElement[]>
-  ? Element[]
+  ? WebdriverIO.Element[]
   : T extends HTMLElement[]
-  ? Element[]
+  ? WebdriverIO.Element[]
   : T extends null
   ? null
   : never

test/configure.e2e.ts renamed to test/async/configure.e2e.ts

@@ -1,4 +1,4 @@
-import {setupBrowser, configure} from '../src'
+import {setupBrowser, configure} from '../../src'
 
 describe('configure', () => {
   afterEach(() => {

test/queries.e2e.ts renamed to test/async/queries.e2e.ts

@@ -1,4 +1,4 @@
-import {setupBrowser} from '../src'
+import {setupBrowser} from '../../src'
 
 describe('queries', () => {
   it('queryBy resolves with matching element', async () => {

test/setupBrowser.e2e.ts renamed to test/async/setupBrowser.e2e.ts

@@ -1,15 +1,7 @@
 import path from 'path'
 import {queries as baseQueries} from '@testing-library/dom'
 
-import {setupBrowser} from '../src'
-import {WebdriverIOQueries} from '../src/types'
-
-declare global {
-  namespace WebdriverIO {
-    interface Browser extends WebdriverIOQueries {}
-    interface Element extends WebdriverIOQueries {}
-  }
-}
+import {setupBrowser} from '../../src'
 
 describe('setupBrowser', () => {
   it('resolves with all queries', () => {
@@ -49,7 +41,7 @@ describe('setupBrowser', () => {
 
     await browser.reloadSession()
     await browser.url(
-      `file:///${path.join(__dirname, '../test-app/index.html')}`,
+      `file:///${path.join(__dirname, '../../test-app/index.html')}`,
     )
 
     expect(await getByText('Page Heading')).toBeDefined()

test/async/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "types": ["node", "webdriverio", "@wdio/mocha-framework"],
+    "baseUrl": "."
+  },
+  "exclude": [],
+  "include": ["**/*.ts"]
+}

test/async/types.ts

@@ -0,0 +1,8 @@
+import {WebdriverIOQueries} from '../../src'
+
+declare global {
+  namespace WebdriverIO {
+    interface Browser extends WebdriverIOQueries {}
+    interface Element extends WebdriverIOQueries {}
+  }
+}

test/within.e2e.ts renamed to test/async/within.e2e.ts

@@ -1,4 +1,4 @@
-import {within, setupBrowser} from '../src';
+import {within, setupBrowser} from '../../src'
 
 describe('within', () => {
   it('scopes queries to element', async () => {