Proposed changes

This patch adds a new command called addInitScript that makes it very easy to use Bidi's script.addPreloadScript functionality, e.g.:

const reset = await browser.addInitScript((seed) => {
    Math.random = () => seed
}, 42)

await browser.url('https://webdriver.io')
console.log(await browser.execute(() => Math.random())) // returns 42

await reset()
await browser.url('https://webdriver.io')
console.log(await browser.execute(() => Math.random())) // returns a random number

Furthermore it adds an onBeforeLoad option that initiates a preload script for 1 single navigation. This can be used to make manipulating the environment very easy, e.g.:

await browser.url('https://pazguille.github.io/demo-battery-api/', {
    onBeforeLoad (win) {
        // mock "navigator.battery" property
        // returning mock charge object
        win.navigator.getBattery = () => Promise.resolve({
            level: 0.5,
            charging: false,
            chargingTime: Infinity,
            dischargingTime: 3600, // seconds
        })
    }
})
// now we can assert actual text - we are charged at 50%
console.log(await browser.$('.battery-percentage').getText())
// and has enough juice for 1 hour
console.log(await browser.$('.battery-remaining').getText())

Types of changes

• Polish (an improvement for an existing feature)
• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update (improvements to the project's docs)
• Specification changes (updates to WebDriver command specifications)
• Internal updates (everything related to internal scripts, governance documentation and CI files)

Checklist

• I have read the CONTRIBUTING doc
• I have added tests that prove my fix is effective or that my feature works
• I have added the necessary documentation (if appropriate)
• I have added proper type definitions for new commands (if appropriate)

Backport Request

//: # (The current main branch is the development branch for WebdriverIO v9. If your change should be released to the current major version of WebdriverIO (v8), please raise another PR with the same changes against the v8 branch.)

• This change is solely for v9 and doesn't need to be back-ported
• Back-ported PR at #XXXXX

Further comments

n/a

Reviewers: @webdriverio/project-committers