Custom Matchers
WebdriverIO uses a Jest style expect assertion library that comes with special features and custom matchers specific for running web and mobile tests. While the library of matchers is big, it certainly doesn't fit all possible situations. Therefore it is possible to extend the existing matchers with custom ones defined by you.
While there is currently no difference in how matchers are defined that are specific to the browser object or an element instance, this certainly might change in the future. Keep an eye on webdriverio/expect-webdriverio#1408 for further information on this development.
Custom Browser Matchers
To register a custom browser matcher, call extend on the expect object either in your spec file directly or as part of the e.g. before hook in your wdio.conf.js:
loading...
As shown in the example the matcher function takes the expected object, e.g. the browser or element object, as the first parameter and the expected value as the second. You can then use the matcher as follows:
loading...
Custom Element Matchers
Similar to custom browser matchers, element matchers don't differ. Here is an example of how to create a custom matcher to assert the aria-label of an element:
loading...
This allows you to call the assertion as follows:
loading...
TypeScript Support
If you are using TypeScript, one more step is required to ensure the type safety of your custom matchers. By extending the Matcher interface with your custom matchers, all type issues vanish:
loading...
If you created a custom asymmetric matcher, you can similarly extend the expect types as follows:
declare global {
namespace ExpectWebdriverIO {
interface AsymmetricMatchers {
myCustomMatcher(value: string): ExpectWebdriverIO.PartialMatcher;
}
}
}
