1---
2title: Choose Browser-Based Runner for Style and DOM Event Testing
3impact: MEDIUM
4impactDescription: Node-based runners cannot test real CSS behavior, native DOM events, cookies, or computed styles
5type: capability
6tags: [vue3, testing, component-testing, vitest, browser, jsdom]
7---
8 
9# Choose Browser-Based Runner for Style and DOM Event Testing
10 
11**Impact: MEDIUM** - Node-based test runners (Vitest with jsdom/happy-dom) simulate the DOM but cannot test real CSS rendering, native browser events, cookies, computed styles, or cross-browser behavior. Use browser-based runners when these matter.
12 
13Use Vitest for most component tests (fast), but use Vitest Browser Mode when testing visual/DOM-dependent features.
14 
15## Task Checklist
16 
17- [ ] Use Vitest (node) for logic-focused component tests
18- [ ] Use Vitest Browser Mode for style-dependent tests
19- [ ] Use Vitest Browser Mode for native events (focus, drag, resize)
20- [ ] Use Vitest Browser Mode for cookies and computed CSS styles
21- [ ] Accept slower speed tradeoff for browser accuracy
22 
23## When to Use Each Approach
24 
25### Node-Based Runner (Vitest + happy-dom/jsdom)
26Best for:
27- Pure logic testing
28- State management
29- Event emission
30- Props/slots behavior
31- Most component interactions
32- Fast CI/CD pipelines
33 
34```javascript
35// vitest.config.js
36export default defineConfig({
37  test: {
38    environment: 'happy-dom',  // or 'jsdom'
39  }
40})
41```
42 
43```javascript
44// Fast but limited - fine for most tests
45test('button emits click event', async () => {
46  const wrapper = mount(Button)
47  await wrapper.trigger('click')
48  expect(wrapper.emitted('click')).toBeTruthy()
49})
50```
51 
52### Vitest Browser Mode
53Required for:
54- CSS computed styles verification
55- CSS transitions/animations
56- Real focus/blur behavior
57- Drag and drop
58- Cookie operations
59- Viewport-dependent behavior
60- Cross-browser validation
61 
62## Vitest Browser Mode Setup
63 
64```bash
65npm install -D @vitest/browser playwright
66```
67 
68```javascript
69// vitest.config.js
70import { defineConfig } from 'vitest/config'
71 
72export default defineConfig({
73  test: {
74    browser: {
75      enabled: true,
76      name: 'chromium',
77      provider: 'playwright',
78    },
79  },
80})
81```
82 
83```javascript
84// Button.browser.test.js
85import { render } from 'vitest-browser-vue'
86import Button from './Button.vue'
87 
88test('has correct hover styling', async () => {
89  const { getByRole } = render(Button, { props: { label: 'Click me' } })
90 
91  const button = getByRole('button')
92 
93  // Check initial style
94  await expect.element(button).toHaveStyle({
95    backgroundColor: 'rgb(59, 130, 246)'  // blue
96  })
97})
98 
99test('maintains focus after click', async () => {
100  const { getByRole } = render(Button)
101 
102  const button = getByRole('button')
103  await button.click()
104 
105  await expect.element(button).toHaveFocus()
106})
107```
108 
109## Examples: What Each Runner Can/Cannot Test
110 
111### Styles - Browser Required
112```javascript
113// Node runner: CANNOT verify actual CSS
114test('danger button has red background', () => {
115  const wrapper = mount(Button, { props: { variant: 'danger' } })
116  // This only checks class exists, not actual color
117  expect(wrapper.classes()).toContain('bg-red-500')
118})
119 
120// Vitest Browser Mode: CAN verify computed styles
121test('danger button renders red', async () => {
122  const { getByRole } = render(Button, { props: { variant: 'danger' } })
123  await expect.element(getByRole('button')).toHaveStyle({
124    backgroundColor: 'rgb(239, 68, 68)'
125  })
126})
127```
128 
129### Computed CSS Styles - Browser Required
130```javascript
131// Node runner: CANNOT get real computed styles
132test('button has correct padding', () => {
133  const wrapper = mount(Button)
134  // getComputedStyle returns empty/default values in jsdom
135  const style = window.getComputedStyle(wrapper.element)
136  // style.padding will be empty string, not actual computed value
137})
138 
139// Vitest Browser Mode: Real computed styles
140test('button has correct padding', async () => {
141  const { getByRole } = render(Button)
142  const button = getByRole('button')
143 
144  await expect.element(button).toHaveStyle({
145    padding: '12px 24px'
146  })
147})
148```
149 
150### Native Events - Browser Required
151```javascript
152// Node runner: Synthetic events only
153test('handles drag and drop', async () => {
154  const wrapper = mount(DraggableList)
155  // trigger('dragstart') is synthetic - may not work as expected
156  await wrapper.find('.item').trigger('dragstart')
157})
158 
159// Vitest Browser Mode: Real native events via userEvent
160import { userEvent } from '@vitest/browser/context'
161 
162test('reorders items on drag', async () => {
163  const { getByTestId } = render(DraggableList)
164 
165  const item = getByTestId('item-1')
166  const target = getByTestId('item-3')
167 
168  await userEvent.dragAndDrop(item, target)
169 
170  // Assert reordering
171})
172```
173 
174## Recommended Testing Strategy
175 
176```javascript
177// vitest.config.js - Separate test configurations
178 
179export default defineConfig({
180  test: {
181    // Default: Node environment for speed
182    environment: 'happy-dom',
183 
184    // Browser tests in separate directory
185    include: ['src/**/*.test.{js,ts}'],
186  },
187})
188 
189// Run browser tests separately
190// npx vitest --browser.enabled
191```
192 
193### Directory Structure
194```
195tests/
196├── unit/              # Fast node-based tests
197│   ├── Button.test.js
198│   └── useCounter.test.js
199├── component/         # Slower browser-based tests
200│   ├── Button.browser.test.js
201│   └── DragDrop.browser.test.js
202└── e2e/               # Full E2E tests (Playwright)
203    └── user-flow.spec.ts
204```
205 
206## Reference
207- [Vue.js Testing - Component Testing](https://vuejs.org/guide/scaling-up/testing#component-testing)
208- [Vitest Browser Mode](https://vitest.dev/guide/browser.html)
209