docs(testing): adding WebdriverIO docs

docs/testing/01-overview.md

@@ -30,9 +30,10 @@ expects to receive the event `Z`.
 Stencil currently supports the following tools for testing components:
 
 - [__Stencil Test Runner__](./stencil-testrunner/01-overview.md): a built-in test runner based on Jest for unit and end-to-end testing with Puppeteer to run within an actual browser in order to provide more realistic results.
+- [__WebdriverIO__](./webdriverio/01-overview.md): the next-gen browser and mobile automation test framework for Node.js that allows you to run component and end-to-end tests across all browser.
 
 :::info
 
-We are actively working supporting a more wider range of testing tools, including Playwright and WebdriverIO. Stay tuned for updates!
+We are actively working supporting a more wider range of testing tools, including Playwright. Stay tuned for updates!
 
 :::

docs/testing/webdriverio/01-overview.md

@@ -0,0 +1,35 @@
+---
+title: WebdriverIO Overview
+sidebar_label: Overview
+---
+
+# Overview
+
+WebdriverIO is a progressive automation framework built to automate modern web and mobile applications. It simplifies the interaction with your app and provides a set of plugins that help you create a scalable, robust and stable test suite.
+
+Testing with WebdriverIO has the following advantages:
+
+- __Cross Browser Support__: WebdriverIO is designed to support all platforms, either on desktop or mobile. You can run tests on actual browser your users are using, including covering different versions of them.
+- __Real User Interaction__: Interacting with elements in WebdriverIO through the WebDriver protocol is the closes you can get to reality compared to emulated interaction in virtual DOM environments.
+- __Web Platform Support__: Running tests in actual browser allows you to tap into the latest Web Platform features for testing your components, often not available when using virtual DOM environments.
+
+## Set Up
+
+To get started with WebdriverIO, all you need to do is to run their project starter:
+
+```sh
+npm init wdio@latest .
+```
+
+This will initiate WebdriverIOs configuration wizard that walks you through the setup. Make sure you select the following options when walking through it:
+
+- __What type of testing would you like to do?__: select either `Component or Unit Testing - in the browser` if you are interested adding unit tests for your components or `E2E Testing - of Web or Mobile Applications` if you like to test your whole application (you can always add either of them later on)
+- __Which framework do you use for building components?__: if you select _Component or Unit Testing_ make sure to select `StencilJS` as preset so WebdriverIO knows how to compile your components properly
+
+The following questions can be answered as desired. Once setup the wizard has created a `wdio.conf.ts` file and a `wdio` script to run your tests. You should be able to run your first test on the auto-generated test file via:
+
+```sh
+npm run wdio
+```
+
+More information on setting up WebdriverIO can be found in their [documentation](https://webdriver.io/docs/component-testing/stencil).

docs/testing/webdriverio/02-unit-testing.md

@@ -0,0 +1,56 @@
+---
+title: Unit Testing
+sidebar_label: Unit Testing
+description: Unit Testing
+slug: /testing/webdriverio/unit-testing
+---
+
+# Unit Testing
+
+WebdriverIO makes it easy to unit test components and app utility functions in the browser. Unit tests validate the code in isolation. Well written tests are fast, repeatable, and easy to reason about. It tries to follow a simple guiding principle: the more your tests resemble the way your software is used, the more confidence they can give you.
+
+### Test Setup
+
+To resemble how your component is being used as close as possible to reality we need to render it into an actual DOM tree. WebdriverIO provides a helper package for this that you can use called `@wdio/browser-runner/stencil`. It exports a `render ` method that allows us to mount our component to the DOM.
+
+For example, given the following component:
+
+```ts reference title="/src/components/my-component/my-component.tsx"
+https://github.com/webdriverio/component-testing-examples/blob/main/stencil-component-starter/src/components/my-component/my-component.tsx
+```
+
+We import the component into our test to render it in the browser:
+
+```ts reference title="/src/components/my-component/my-component.test.tsx"
+https://github.com/webdriverio/component-testing-examples/blob/main/stencil-component-starter/src/components/my-component/my-component.test.tsx#L2-L18
+```
+
+You can find more information about the `render` methods option and its return object in the WebdriverIO [documentation](https://webdriver.io/docs/component-testing/stencil#render-options).
+
+### Handle Asynchronicity
+
+Instead of directly working on DOM objects, with WebdriverIO you are interacting with references of DOM nodes and interact through WebDriver commands that are async. Make sure you always use an `await` to ensure that all commands and assertion are executed sequentially.
+
+:::info
+
+Missing an `await` can be a simple oversight and can cause us long hours of debugging. To avoid this and ensure promises are handled properly, it is recommended to use an ESLint rule called [`require-await`](https://eslint.org/docs/latest/rules/require-await).
+
+:::
+
+### Matcher
+
+WebdriverIO provides their own matcher to assert an element in various ways. We recommend to use them over synchronous matcher like `toBe` or `toEqual` as they allow for retries and make your tests more resilient against flakiness.
+
+For example, instead of asserting the content of a component like this:
+
+```ts
+expect(await $('my-component').getText()).toBe(`Hello, World! I'm Stencil 'Don't call me a framework' JS`)
+```
+
+It is better to use WebdriverIOs matcher for asserting text:
+
+```ts
+await expect($('my-component')).toHaveText(`Hello, World! I'm Stencil 'Don't call me a framework' JS`)
+```
+
+You can read more about WebdriverIOs specific matcher, in the project [documentation](https://webdriver.io/docs/api/expect-webdriverio).

docs/testing/webdriverio/03-mocking.md

@@ -0,0 +1,34 @@
+---
+title: Mocking
+sidebar_label: Mocking
+description: Mocking
+label: Mocking
+---
+
+# Mocking
+
+WebdriverIO has support for file based module mocking as well as mocking of entire dependencies of your project. The framework provides a set of primitives for mocking as documented in the project [documentation](https://webdriver.io/docs/component-testing/mocking):
+
+```ts
+import { mock, fn, unmock } from '@wdio/browser-runner'
+```
+
+To create a mock you can either create a file with the name of the module you like to mock the `__mocks__` directory, as described in [Manual Mocks](https://webdriver.io/docs/component-testing/mocking#manual-mocks), or mock the file directly as part of your test:
+
+```ts
+import { mock, fn } from '@wdio/browser-runner'
+import { format } from './utils/utils.ts'
+
+// mock files within the project
+mock('./utils/utils.ts', () => {
+    format: fn().mockReturnValue(42)
+})
+// mock whole modules and replace functionality with what is defined in `./__mocks__/leftpad.ts`
+mock('leftpad')
+
+console.log(format()) // returns `42`
+```
+
+Once a module is mocked, importing it either from your test or your component will give you the mocked version of the module and not the actual one.
+
+Find more examples and documentation on mocking in the project [documentation](https://webdriver.io/docs/component-testing/mocking).

docs/testing/webdriverio/_category_.json

@@ -0,0 +1,4 @@
+{
+    "label": "WebdriverIO"
+  }
+