From 60c0e1206f4247e4dfd65c92a7bfc186f843b19c Mon Sep 17 00:00:00 2001
From: Christian Bromann <git@bromann.dev>
Date: Mon, 8 Jan 2024 17:27:27 -0800
Subject: [PATCH] [docs] add docs for testing Lit components with WebdriverIO
 (#1287)

---
 .../site/docs/v3/tools/testing.md             | 50 ++++++++++++++++++-
 1 file changed, 48 insertions(+), 2 deletions(-)

diff --git a/packages/lit-dev-content/site/docs/v3/tools/testing.md b/packages/lit-dev-content/site/docs/v3/tools/testing.md
index c89608556..5ea2d9e61 100644
--- a/packages/lit-dev-content/site/docs/v3/tools/testing.md
+++ b/packages/lit-dev-content/site/docs/v3/tools/testing.md
@@ -15,7 +15,7 @@ See the [Starter Kits](/docs/v3/tools/starter-kits/) documentation for an easy t
 
 ## Selecting a test framework
 
-Lit is a standard modern Javascript library, and you can use virtually any Javascript testing framework to test your Lit code. There are many popular options, including [Jest](https://jestjs.io/), [Karma](https://karma-runner.github.io/), [Mocha](https://mochajs.org/), [Jasmine](https://jasmine.github.io/), and [Web Test Runner](https://modern-web.dev/docs/test-runner/overview/).
+Lit is a standard modern Javascript library, and you can use virtually any Javascript testing framework to test your Lit code. There are many popular options, including [Jest](https://jestjs.io/), [Karma](https://karma-runner.github.io/), [Mocha](https://mochajs.org/), [Jasmine](https://jasmine.github.io/), [WebdriverIO](https://webdriver.io) and [Web Test Runner](https://modern-web.dev/docs/test-runner/overview/).
 
 There are a few things you'll want to make sure your testing environment supports to effectively test your Lit code.
 
@@ -37,7 +37,7 @@ To test on older browsers, your test environment will need to load some polyfill
 
 ## Using Web Test Runner { #web-test-runner }
 
-We recommend using [Web Test Runner](https://modern-web.dev/docs/test-runner/overview/) since it is specifically designed to test modern web libraries like Lit using modern web features like custom elements and shadow DOM. See the [Getting Started](https://modern-web.dev/guides/test-runner/getting-started) documentation for Web Test Runner.
+[Web Test Runner](https://modern-web.dev/docs/test-runner/overview/) is specifically designed to test modern web libraries like Lit using modern web features like custom elements and shadow DOM. See the [Getting Started](https://modern-web.dev/guides/test-runner/getting-started) documentation for Web Test Runner.
 
 In order to support older browsers, you need to configure Web Test Runner as follows:
 
@@ -75,3 +75,49 @@ export default {
 };
 ```
 
+## Using WebdriverIO
+
+[WebdriverIO](https://webdriver.io) is a good option for your component or end-to-end tests. It has very compelling advantages like support for [mocking](https://webdriver.io/docs/component-testing/mocking) and [code coverage](https://webdriver.io/docs/component-testing/coverage) reporting.
+
+You can set up WebdriverIO in your project via:
+
+```bash
+npm init wdio@latest ./
+```
+
+It will start a configuration wizard that will guide you through some questions. Make sure select the following:
+
+- __What type of testing would you like to do?__<br>Component or Unit Testing - in the browser
+- __Which framework do you use for building components?__<br>Lit
+
+The remaining questions can be answered as desired.
+
+In order test the component you have to render it into the test page before the test starts and ensure it gets cleaned up afterwards:
+
+```ts
+import { expect, $ } from '@wdio/globals'
+
+// Component.ts contains the <simple-greeting> component implemented the same as:
+// https://lit.dev/docs/components/overview/
+import './components/Component.ts'
+
+describe('Lit Component testing', () => {
+    let elem: HTMLElement
+
+    beforeEach(() => {
+        elem = document.createElement('simple-greeting')
+    })
+
+    it('should render component', async () => {
+        elem.setAttribute('name', 'WebdriverIO')
+        document.body.appendChild(elem)
+        await expect($(elem)).toHaveText('Hello, WebdriverIO!')
+    })
+
+    afterEach(() => {
+        elem.remove()
+    })
+})
+```
+
+Find more information on [element assertions](https://webdriver.io/docs/api/expect-webdriverio), [finding elements](https://webdriver.io/docs/selectors#deep-selectors) within the Shadow DOM and [more](https://webdriver.io/docs/component-testing) in the WebdriverIO documentation.