Workflow:Webdriverio Webdriverio Component Testing
| Knowledge Sources | |
|---|---|
| Domains | Browser_Automation, Component_Testing, Frontend_Development |
| Last Updated | 2026-02-12 01:30 GMT |
Overview
End-to-end process for testing frontend framework components (Vue, React, Svelte, Lit, Preact) in isolation within a real browser using WebdriverIO's browser runner with Vite.
Description
This workflow demonstrates how to use WebdriverIO's @wdio/browser-runner to execute component-level tests directly in the browser. Unlike traditional E2E tests that navigate full pages, component tests render individual components in isolation using the @testing-library render API, then interact with them using WebdriverIO commands. The browser runner leverages Vite as the dev server to compile and serve components, providing fast hot-module-replacement and native ES module support. This combines the realism of browser-based testing with the speed and focus of unit testing.
Usage
Execute this workflow when you want to test individual UI components in a real browser environment without running a full application. This is ideal for component libraries, design systems, or when you need to verify component behavior, rendering, event handling, and accessibility in actual browser conditions rather than a JSDOM simulation.
Execution Steps
Step 1: Install Browser Runner
Install @wdio/browser-runner alongside the standard WDIO packages. This runner replaces the default @wdio/local-runner and sets up a Vite-based environment for compiling and serving components in the browser.
Key considerations:
- Install @wdio/browser-runner as a dev dependency
- Install the @testing-library package for your framework (e.g., @testing-library/vue, @testing-library/react)
- A Vite config file (vite.config.ts) is needed for framework-specific plugins
Step 2: Configure Browser Runner
Set the runner option in wdio.conf.ts to use the browser runner with a Vite configuration. Point specs to component test files (co-located with components or in a test directory). The Vite config must include the appropriate framework plugin.
Key considerations:
- The runner field uses an array format: ['browser', { viteConfig, rootDir }]
- Import the existing vite.config.ts and pass it to the runner
- The rootDir option specifies the project root for resolving imports
- Test files are typically co-located with components (e.g., Component.test.ts next to Component.vue)
Step 3: Write Component Tests
Create test files that import the render function from @testing-library and the component under test. Use render() to mount the component in the browser, query for elements using Testing Library queries, and interact with them using WebdriverIO commands. Combine Testing Library's DOM queries with WebdriverIO's expect matchers.
Key considerations:
- Use render(Component) to mount the component in the browser
- Testing Library queries (getByText, getByRole) find elements in the rendered output
- Wrap Testing Library results with $() to get WebdriverIO element instances for interaction
- Use expect-webdriverio matchers (toHaveText, toBeDisplayed) for assertions
- Components are rendered in isolation without the full application context
Step 4: Handle Component Props and State
Pass props, provide stores, and mock dependencies when rendering components. Testing Library's render options support framework-specific context injection (Vuex/Pinia stores, React context providers, etc.).
Key considerations:
- Pass props directly to the render() function
- Framework-specific options handle global plugins and providers
- Test component behavior by simulating user interactions (clicks, input) and verifying output changes
- Verify emitted events, computed properties, and reactive state through the DOM
Step 5: Run Component Tests
Execute the component test suite using npx wdio run wdio.conf.ts. The browser runner starts a Vite dev server, opens a browser, and runs tests within it. Results are reported using standard WDIO reporters.
Key considerations:
- Vite provides fast compilation with HMR support
- Tests run in a real browser, not a simulated DOM
- The same WDIO reporter infrastructure works for component tests
- Multiple browser capabilities can be tested in parallel