feat: Alpha Support for Multi-remote Browser

docs/MultiRemote.md

@@ -0,0 +1,155 @@
+# MultiRemote Support (Alpha)
+
+Multi-remote support is in active development.
+
+## Usage
+
+By default, multi-remote matchers fetch data (e.g., `getTitle`) from all remotes, simplifying tests where browsers share the same behavior.
+
+Use the typed global constants:
+```ts
+import { multiremotebrowser as multiRemoteBrowser } from '@wdio/globals' 
+...
+await expect(multiRemoteBrowser).toHaveTitle('...')
+```
+Note: `multiRemoteBrowser` is used in examples pending a planned rename.
+
+
+Assuming the following WebdriverIO multi-remote configuration:
+```ts
+export const config: WebdriverIO.MultiremoteConfig = {
+    ...
+    capabilities: {
+        myChromeBrowser: {
+            capabilities: {
+                browserName: 'chrome',
+                'goog:chromeOptions': { args: ['--headless'] }
+            }
+        },
+        myFirefoxBrowser: {
+            capabilities: {
+                browserName: 'firefox',
+                'moz:firefoxOptions': { args: ['-headless'] }
+            }
+        } 
+    },
+    ...
+}
+```
+
+And an `it` test like:
+```ts
+import { multiremotebrowser as multiRemoteBrowser } from '@wdio/globals' 
+
+it('should have title "My Site Title"', async function () {
+    await multiRemoteBrowser.url('https://mysite.com')
+
+    // ... assertions
+})
+```            
+
+
+## Single Expected Value
+To test all remotes against the same value, pass a single expected value.
+```ts
+    await expect(multiRemoteBrowser).toHaveTitle('My Site Title')
+```
+
+## Multiple Expected Values
+For differing remotes, pass an array of expected values.
+  - Note: Values must match the configuration order.
+```ts
+    await expect(multiRemoteBrowser).toHaveTitle(['My Chrome Site Title', 'My Firefox Site Title'])
+```
+
+## **NOT IMPLEMENTED** Per Remote Expected Value
+To test specific remotes, map instance names to expected values.
+
+```ts
+    // Test both defined remotes with specific values
+    await expect(multiRemoteBrowser).toHaveTitle({
+        'myChromeBrowser' : 'My Chrome Site Title', 
+        'myFirefoxBrowser' : 'My Firefox Site Title'
+    })
+```
+
+To assert a single remote and skip others:
+```ts
+    await expect(multiRemoteBrowser).toHaveTitle({
+        'myFirefoxBrowser' : 'My Firefox Site Title'
+    })
+```
+
+To assert all remotes with a default value, overriding specific ones:
+```ts
+    await expect(multiRemoteBrowser).toHaveTitle({
+        default : 'My Default Site Title',
+        'myFirefoxBrowser' : 'My Firefox Site Title'
+    })
+```
+
+## Limitations
+- Options (e.g., `StringOptions`) apply globally.
+- Alpha support is limited to the `toHaveTitle` browser matcher.
+- Element matchers are planned.
+- Assertions currently throw on the first error. Future updates will report thrown errors as failures, and will only throw if all remotes fail.
+- SoftAssertions, snapshot services and network matchers might come after.
+
+## Alternatives
+
+Since multi-remote instances are standard browsers, you can also assert by iterating over the instance list.
+
+### Parameterized Tests
+Using the parameterized feature of your test framework, you can iterate over the multi-remote instances.
+
+Mocha Parameterized Example
+```ts
+    describe('Multiremote test', async () => {
+        multiRemoteBrowser.instances.forEach(function (instance) {
+            describe(`Test ${instance}`, function () {
+                it('should have title "My Site Title"', async function () {
+                    const browser = multiRemoteBrowser.getInstance(instance)
+                    await browser.url('https://mysite.com')
+
+                    await expect(browser).toHaveTitle("My Site Title")
+                })
+            })
+        })
+    })
+```
+### Direct Instance Access (TypeScript)
+By extending the WebdriverIO `namespace` in TypeScript (see [documentation](https://webdriver.io/docs/multiremote/#extending-typescript-types)), you can directly access each instance and use `expect` on them.
+
+```ts
+    it('should have title per browsers', async () => {
+        await multiRemoteBrowser.url('https://mysite.com')
+
+        await expect(multiRemoteBrowser.myChromeBrowser).toHaveTitle('My Chrome Site Title')
+        await expect(multiRemoteBrowser.myFirefoxBrowser).toHaveTitle('My Firefox Site Title')
+    }) 
+```
+
+Required configuration:
+
+File `type.d.ts`
+```ts
+declare namespace WebdriverIO {
+    interface MultiRemoteBrowser {
+        myChromeBrowser: WebdriverIO.Browser
+        myFirefoxBrowser: WebdriverIO.Browser
+    }
+}
+```
+
+In `tsconfig.json`
+```json
+{
+  "compilerOptions": {
+    ...
+  },
+  "include": [
+    ...
+    "type.d.ts"
+  ]
+}
+```

src/matchers/browser/toHaveTitle.ts

@@ -1,39 +1,66 @@
-import { waitUntil, enhanceError, compareText } from '../../utils.js'
+import { compareText, waitUntilResultSucceed } from '../../utils.js'
 import { DEFAULT_OPTIONS } from '../../constants.js'
+import type { MaybeArray } from '../../util/multiRemoteUtil.js'
+import {  mapExpectedValueWithInstances } from '../../util/multiRemoteUtil.js'
+import { formatFailureMessage } from '../../util/formatMessage.js'
 
+type ExpectedValueType = string | RegExp | WdioAsymmetricMatcher<string>
+
+export async function toHaveTitle(
+    this: ExpectWebdriverIO.MatcherContext,
+    browsers: WebdriverIO.MultiRemoteBrowser,
+    expectedValues: MaybeArray<ExpectedValueType>,
+    options?: ExpectWebdriverIO.StringOptions,
+): Promise<ExpectWebdriverIO.AssertionResult>
 export async function toHaveTitle(
+    this: ExpectWebdriverIO.MatcherContext,
     browser: WebdriverIO.Browser,
-    expectedValue: string | RegExp | WdioAsymmetricMatcher<string>,
-    options: ExpectWebdriverIO.StringOptions = DEFAULT_OPTIONS
+    expectedValue: ExpectedValueType,
+    options?: ExpectWebdriverIO.StringOptions,
+): Promise<ExpectWebdriverIO.AssertionResult>
+export async function toHaveTitle(
+    this: ExpectWebdriverIO.MatcherContext,
+    browser: WebdriverIO.Browser | WebdriverIO.MultiRemoteBrowser,
+    expectedValue: MaybeArray<ExpectedValueType>,
+    options: ExpectWebdriverIO.StringOptions = DEFAULT_OPTIONS,
 ) {
-    const isNot = this.isNot
-    const { expectation = 'title', verb = 'have' } = this
+    const { expectation = 'title', verb = 'have', isNot } = this
+    const context = { expectation, verb, isNot, isMultiRemote: browser.isMultiremote }
 
     await options.beforeAssertion?.({
         matcherName: 'toHaveTitle',
         expectedValue,
         options,
     })
 
-    let actual
-    const pass = await waitUntil(async () => {
-        actual = await browser.getTitle()
+    const browsersWithExpected = mapExpectedValueWithInstances(browser, expectedValue)
+
+    const conditions = Object.entries(browsersWithExpected).map(([instanceName, { browser, expectedValue: expected }]) => async () => {
+        const actual = await browser.getTitle()
 
-        return compareText(actual, expectedValue, options).result
-    }, isNot, options)
+        const result = compareText(actual, expected, options)
+        result.instance = instanceName
+        return result
+    })
+
+    const conditionsResults = await waitUntilResultSucceed(
+        conditions,
+        isNot,
+        options,
+    )
 
-    const message = enhanceError('window', expectedValue, actual, this, verb, expectation, '', options)
-    const result: ExpectWebdriverIO.AssertionResult = {
-        pass,
-        message: () => message
+    const message = formatFailureMessage('window', conditionsResults.results, context, '', options)
+    const assertionResult: ExpectWebdriverIO.AssertionResult = {
+        pass: conditionsResults.pass,
+        message: () => message,
     }
 
     await options.afterAssertion?.({
         matcherName: 'toHaveTitle',
         expectedValue,
         options,
-        result
+        result: assertionResult,
     })
 
-    return result
+    return assertionResult
 }

src/util/formatMessage.ts

@@ -2,6 +2,7 @@ import { printDiffOrStringify, printExpected, printReceived } from 'jest-matcher
 import { equals } from '../jasmineUtils.js'
 import type { WdioElements } from '../types.js'
 import { isElementArray } from './elementsUtil.js'
+import type { CompareResult } from '../utils.js'
 
 const EXPECTED_LABEL = 'Expected'
 const RECEIVED_LABEL = 'Received'
@@ -39,18 +40,19 @@ export const getSelectors = (el: WebdriverIO.Element | WdioElements) => {
     return selectors.reverse().join('.')
 }
 
-export const not = (isNot: boolean): string => {
-    return `${isNot ? 'not ' : ''}`
-}
+const not = (isNot: boolean): string => `${isNot ? 'not ' : ''}`
+
+const startSpace = (word = ''): string | undefined => word ? ` ${word}` : word
 
 export const enhanceError = (
     subject: string | WebdriverIO.Element | WdioElements,
     expected: unknown,
     actual: unknown,
-    context: { isNot: boolean },
+    context: { isNot?: boolean },
     verb: string,
     expectation: string,
-    arg2 = '', {
+    arg2 = '',
+    {
         message = '',
         containing = false
     }): string => {
@@ -85,10 +87,76 @@ export const enhanceError = (
         arg2 = ` ${arg2}`
     }
 
+    /**
+     * Example of below message:
+     * Expect window to have title
+     *
+     * Expected: "some Title text"
+     * Received: "some Wrong Title text"
+     */
     const msg = `${message}Expect ${subject} ${not(isNot)}to ${verb}${expectation}${arg2}${contain}\n\n${diffString}`
     return msg
 }
 
+/**
+ * Formats failure message for multiple compare results
+ * TODO multi-remote support: Replace enhanceError with this one everywhere
+ */
+export const formatFailureMessage = (
+    subject: string | WebdriverIO.Element | WebdriverIO.ElementArray,
+    compareResults: CompareResult<string, string | RegExp | WdioAsymmetricMatcher<string>>[],
+    context: ExpectWebdriverIO.MatcherContext & { useNotInLabel?: boolean },
+    expectedValueArgument2 = '',
+    { message = '', containing = false } = {}): string => {
+
+    const { isNot = false, expectation, useNotInLabel = true, verb } = context
+
+    subject = typeof subject === 'string' ? subject : getSelectors(subject)
+
+    const contain = containing ? 'containing' : ''
+    const customMessage = message ? `${message}\n` : ''
+
+    const label =  {
+        expected: isNot && useNotInLabel ? 'Expected [not]' : 'Expected',
+        received: isNot && useNotInLabel ? 'Received      ' : 'Received'
+    }
+
+    const failedResults = compareResults.filter(({ result }) => result === isNot)
+
+    let msg = ''
+    for (const failResult of failedResults) {
+        const { actual, expected, instance: instanceName } = failResult
+
+        // Using `printDiffOrStringify()` with equals values output `Received: serializes to the same string`, so we need to tweak.
+        const diffString = equals(actual, expected) ?`\
+${label.expected}: ${printExpected(expected)}
+${label.received}: ${printReceived(actual)}`
+            : printDiffOrStringify(expected, actual, label.expected, label.received, true)
+
+        const mulitRemoteContext = context.isMultiRemote  ? `for remote "${instanceName}"` : ''
+
+        /**
+         * Example of below message (custom message + multi-remote + isNot case):
+         * ```
+         * My custom error message
+         * Expect window not to have title for remote "browserA"
+         *
+         * Expected not: "some Title text"
+         * Received: "some Wrong Title text"
+         *
+         * ```
+         */
+        msg += `\
+${customMessage}Expect ${subject} ${not(isNot)}to${startSpace(verb)}${startSpace(expectation)}${startSpace(expectedValueArgument2)}${startSpace(contain)}${startSpace(mulitRemoteContext)}
+
+${diffString}
+
+`
+    }
+
+    return msg.trim()
+}
+
 export const enhanceErrorBe = (
     subject: string | WebdriverIO.Element | WebdriverIO.ElementArray,
     pass: boolean,

src/util/multiRemoteUtil.ts

@@ -0,0 +1,36 @@
+import type { Browser } from 'webdriverio'
+
+export const toArray = <T>(value: T | T[] | MaybeArray<T>): T[] => (Array.isArray(value) ? value : [value])
+
+export type MaybeArray<T> = T | T[]
+
+export const isMultiRemote = (browser: WebdriverIO.Browser | WebdriverIO.MultiRemoteBrowser): browser is WebdriverIO.MultiRemoteBrowser => {
+    return (browser as WebdriverIO.MultiRemoteBrowser).isMultiremote === true
+}
+
+type BrowserWithExpected<T> = Record<string, {
+    browser: Browser;
+    expectedValue: T;
+}>
+
+export const mapExpectedValueWithInstances = <T>(browsers: WebdriverIO.Browser | WebdriverIO.MultiRemoteBrowser, expectedValues: T | MaybeArray<T>): BrowserWithExpected<T> => {
+    if (isMultiRemote(browsers)) {
+        if (Array.isArray(expectedValues)) {
+            if (expectedValues.length !== browsers.instances.length) {
+                throw new Error(`Expected values length (${expectedValues.length}) does not match number of browser instances (${browsers.instances.length}) in multi-remote setup.`)
+            }
+        }
+        // TODO multi-remote support: add support for object like { default: 'title', browserA: 'titleA', browserB: 'titleB' } later
+
+        const browsersWithExpected = browsers.instances.reduce((acc: BrowserWithExpected<T>, instance, index) => {
+            const browser = browsers.getInstance(instance)
+            const expectedValue: T = Array.isArray(expectedValues) ? expectedValues[index] : expectedValues
+            acc[instance] = { browser, expectedValue }
+            return acc
+        }, {})
+        return browsersWithExpected
+    }
+
+    // TODO multi-remote support: using default could clash if someone use name default, to review later
+    return { default: { browser: browsers, expectedValue: expectedValues as T } }
+}