devskill 2.0.2

package/skills/vue-testing-best-practices/reference/teleport-testing-complexity.md

@@ -0,0 +1,158 @@
+---
+title: Teleported Content Requires Special Testing Approach
+impact: MEDIUM
+impactDescription: Vue Test Utils cannot find teleported content using standard wrapper.find() methods
+type: gotcha
+tags: [vue3, teleport, testing, vue-test-utils]
+---
+
+# Teleported Content Requires Special Testing Approach
+
+**Impact: MEDIUM** - Vue Test Utils scopes queries to the mounted component. Teleported content renders outside the component's DOM tree, so `wrapper.find()` cannot locate it. This leads to failing tests and confusion.
+
+## Task Checklist
+
+- [ ] Stub Teleport in unit tests to keep content in component tree
+- [ ] Use `document.body` queries for integration tests with real Teleport
+- [ ] Consider using `getComponent()` instead of DOM queries for teleported components
+
+**Problem - Standard Testing Fails:**
+```vue
+<!-- Modal.vue -->
+<template>
+  <button @click="open = true">Open</button>
+  <Teleport to="body">
+    <div v-if="open" class="modal" data-testid="modal">
+      <input type="text" data-testid="modal-input" />
+    </div>
+  </Teleport>
+</template>
+```
+
+```ts
+// Modal.spec.ts - BROKEN
+import { mount } from '@vue/test-utils'
+import Modal from './Modal.vue'
+
+test('modal input exists', async () => {
+  const wrapper = mount(Modal)
+  await wrapper.find('button').trigger('click')
+
+  // FAILS: Teleported content is not in wrapper's DOM tree
+  expect(wrapper.find('[data-testid="modal-input"]').exists()).toBe(true)
+})
+```
+
+**Solution 1 - Stub Teleport:**
+```ts
+import { mount } from '@vue/test-utils'
+import Modal from './Modal.vue'
+
+test('modal input exists', async () => {
+  const wrapper = mount(Modal, {
+    global: {
+      stubs: {
+        // Stub teleport to render content inline
+        Teleport: true
+      }
+    }
+  })
+
+  await wrapper.find('button').trigger('click')
+
+  // Works: Content renders inside wrapper
+  expect(wrapper.find('[data-testid="modal-input"]').exists()).toBe(true)
+})
+```
+
+**Solution 2 - Query Document Body:**
+```ts
+import { mount } from '@vue/test-utils'
+import Modal from './Modal.vue'
+
+test('modal renders to body', async () => {
+  const wrapper = mount(Modal, {
+    attachTo: document.body  // Required for Teleport to work
+  })
+
+  await wrapper.find('button').trigger('click')
+
+  // Query the actual DOM
+  const modal = document.querySelector('[data-testid="modal"]')
+  expect(modal).toBeTruthy()
+
+  const input = document.querySelector('[data-testid="modal-input"]')
+  expect(input).toBeTruthy()
+
+  // Cleanup
+  wrapper.unmount()
+})
+```
+
+**Solution 3 - Custom Teleport Stub with Content Access:**
+```ts
+import { mount, config } from '@vue/test-utils'
+import { h, Teleport } from 'vue'
+import Modal from './Modal.vue'
+
+// Custom stub that renders content in a testable way
+const TeleportStub = {
+  setup(props, { slots }) {
+    return () => h('div', { class: 'teleport-stub' }, slots.default?.())
+  }
+}
+
+test('modal with custom stub', async () => {
+  const wrapper = mount(Modal, {
+    global: {
+      stubs: {
+        Teleport: TeleportStub
+      }
+    }
+  })
+
+  await wrapper.find('button').trigger('click')
+
+  // Content is inside .teleport-stub
+  expect(wrapper.find('.teleport-stub [data-testid="modal-input"]').exists()).toBe(true)
+})
+```
+
+## Testing Vue Final Modal and UI Libraries
+
+Libraries like Vue Final Modal use Teleport internally, causing test failures:
+
+```ts
+// Problem: Vue Final Modal teleports to body
+import { VueFinalModal } from 'vue-final-modal'
+
+test('modal content', async () => {
+  const wrapper = mount(MyComponent, {
+    global: {
+      stubs: {
+        // Stub the modal component to avoid teleport issues
+        VueFinalModal: true
+      }
+    }
+  })
+})
+```
+
+## E2E Testing (Cypress, Playwright)
+
+E2E tests query the real DOM, so Teleport works naturally:
+
+```ts
+// Cypress
+it('opens modal', () => {
+  cy.visit('/page-with-modal')
+  cy.get('button').click()
+
+  // Works: Cypress queries the real DOM
+  cy.get('[data-testid="modal"]').should('be.visible')
+})
+```
+
+## Reference
+- [Vue Test Utils - Teleport](https://test-utils.vuejs.org/guide/advanced/teleport)
+- [Vue Test Utils - Stubs](https://test-utils.vuejs.org/guide/advanced/stubs-shallow-mount)

package/skills/vue-testing-best-practices/reference/testing-async-await-flushpromises.md

@@ -0,0 +1,175 @@
+---
+title: Properly Handle Async Updates with nextTick and flushPromises
+impact: HIGH
+impactDescription: Race conditions and flaky tests occur when async DOM updates or API calls complete after assertions run
+type: gotcha
+tags: [vue3, testing, async, flushPromises, nextTick, vitest, vue-test-utils, race-condition]
+---
+
+# Properly Handle Async Updates with nextTick and flushPromises
+
+**Impact: HIGH** - Vue updates the DOM asynchronously. Without properly awaiting these updates, tests may assert against stale DOM state, causing intermittent failures and false negatives.
+
+Use `await` with triggers and `setValue`, use `nextTick` for reactive updates, and use `flushPromises` for external async operations like API calls.
+
+## Task Checklist
+
+- [ ] Always await `trigger()` and `setValue()` calls
+- [ ] Use `await nextTick()` after programmatic reactive state changes
+- [ ] Use `await flushPromises()` for external async operations (API calls, timers)
+- [ ] Don't chain multiple `nextTick` calls - use `flushPromises` instead
+- [ ] Consider using `waitFor` from testing-library for polling assertions
+
+**Incorrect:**
+```javascript
+import { mount } from '@vue/test-utils'
+import SearchComponent from './SearchComponent.vue'
+
+// BAD: Not awaiting trigger - assertion runs before DOM updates
+test('search filters results', () => {
+  const wrapper = mount(SearchComponent)
+
+  wrapper.find('input').setValue('vue')  // Missing await!
+  wrapper.find('button').trigger('click')  // Missing await!
+
+  // This assertion likely fails - DOM hasn't updated yet
+  expect(wrapper.findAll('.result').length).toBe(3)
+})
+
+// BAD: Using nextTick for API calls
+test('loads data from API', async () => {
+  const wrapper = mount(DataLoader)
+
+  await nextTick()  // This won't wait for the API call!
+
+  // Assertion runs before fetch completes
+  expect(wrapper.find('.data').text()).toBe('Loaded data')
+})
+```
+
+**Correct:**
+```javascript
+import { mount, flushPromises } from '@vue/test-utils'
+import { nextTick } from 'vue'
+import SearchComponent from './SearchComponent.vue'
+import DataLoader from './DataLoader.vue'
+
+// CORRECT: Await trigger and setValue
+test('search filters results', async () => {
+  const wrapper = mount(SearchComponent)
+
+  await wrapper.find('input').setValue('vue')
+  await wrapper.find('button').trigger('click')
+
+  expect(wrapper.findAll('.result').length).toBe(3)
+})
+
+// CORRECT: Use flushPromises for API calls
+test('loads data from API', async () => {
+  const wrapper = mount(DataLoader)
+
+  // Wait for all pending promises to resolve
+  await flushPromises()
+
+  expect(wrapper.find('.data').text()).toBe('Loaded data')
+})
+```
+
+## When to Use Each Method
+
+### `await trigger()` / `await setValue()` - User Interactions
+```javascript
+// These methods return nextTick internally
+await wrapper.find('button').trigger('click')
+await wrapper.find('input').setValue('new value')
+await wrapper.find('form').trigger('submit')
+```
+
+### `await nextTick()` - Programmatic Reactive Updates
+```javascript
+import { nextTick } from 'vue'
+
+test('reflects programmatic state changes', async () => {
+  const wrapper = mount(Counter)
+
+  // Direct state modification (when testing with exposed internals)
+  wrapper.vm.count = 5
+
+  await nextTick()  // Wait for Vue to update DOM
+
+  expect(wrapper.find('.count').text()).toBe('5')
+})
+```
+
+### `await flushPromises()` - External Async Operations
+```javascript
+import { flushPromises } from '@vue/test-utils'
+
+test('displays fetched data', async () => {
+  const wrapper = mount(UserProfile, {
+    props: { userId: 1 }
+  })
+
+  // Wait for component's API call to complete
+  await flushPromises()
+
+  expect(wrapper.find('.username').text()).toBe('John')
+})
+
+// Sometimes you need multiple flushPromises for chained async operations
+test('processes data after fetch', async () => {
+  const wrapper = mount(DataProcessor)
+
+  await flushPromises()  // Wait for fetch
+  await flushPromises()  // Wait for processing triggered by fetch
+
+  expect(wrapper.find('.processed').exists()).toBe(true)
+})
+```
+
+## Common Pattern: Combining Methods
+```javascript
+test('submits form and shows success', async () => {
+  const wrapper = mount(ContactForm)
+
+  // Fill form (awaiting each interaction)
+  await wrapper.find('#name').setValue('John')
+  await wrapper.find('#email').setValue('john@example.com')
+
+  // Submit form
+  await wrapper.find('form').trigger('submit')
+
+  // Wait for API submission to complete
+  await flushPromises()
+
+  // Assert success state
+  expect(wrapper.find('.success-message').exists()).toBe(true)
+})
+```
+
+## Testing with MSW or Mock APIs
+```javascript
+import { flushPromises } from '@vue/test-utils'
+import { rest } from 'msw'
+import { setupServer } from 'msw/node'
+
+const server = setupServer(
+  rest.get('/api/user', (req, res, ctx) => {
+    return res(ctx.json({ name: 'John' }))
+  })
+)
+
+test('displays user data', async () => {
+  const wrapper = mount(UserCard)
+
+  // MSW might require multiple flushPromises
+  await flushPromises()
+  await flushPromises()
+
+  expect(wrapper.find('.name').text()).toBe('John')
+})
+```
+
+## Reference
+- [Vue Test Utils - Asynchronous Behavior](https://test-utils.vuejs.org/guide/advanced/async-suspense)
+- [Vue.js Testing Guide](https://vuejs.org/guide/scaling-up/testing)

package/skills/vue-testing-best-practices/reference/testing-browser-vs-node-runners.md

@@ -0,0 +1,208 @@
+---
+title: Choose Browser-Based Runner for Style and DOM Event Testing
+impact: MEDIUM
+impactDescription: Node-based runners cannot test real CSS behavior, native DOM events, cookies, or computed styles
+type: capability
+tags: [vue3, testing, component-testing, vitest, browser, jsdom]
+---
+
+# Choose Browser-Based Runner for Style and DOM Event Testing
+
+**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.
+
+Use Vitest for most component tests (fast), but use Vitest Browser Mode when testing visual/DOM-dependent features.
+
+## Task Checklist
+
+- [ ] Use Vitest (node) for logic-focused component tests
+- [ ] Use Vitest Browser Mode for style-dependent tests
+- [ ] Use Vitest Browser Mode for native events (focus, drag, resize)
+- [ ] Use Vitest Browser Mode for cookies and computed CSS styles
+- [ ] Accept slower speed tradeoff for browser accuracy
+
+## When to Use Each Approach
+
+### Node-Based Runner (Vitest + happy-dom/jsdom)
+Best for:
+- Pure logic testing
+- State management
+- Event emission
+- Props/slots behavior
+- Most component interactions
+- Fast CI/CD pipelines
+
+```javascript
+// vitest.config.js
+export default defineConfig({
+  test: {
+    environment: 'happy-dom',  // or 'jsdom'
+  }
+})
+```
+
+```javascript
+// Fast but limited - fine for most tests
+test('button emits click event', async () => {
+  const wrapper = mount(Button)
+  await wrapper.trigger('click')
+  expect(wrapper.emitted('click')).toBeTruthy()
+})
+```
+
+### Vitest Browser Mode
+Required for:
+- CSS computed styles verification
+- CSS transitions/animations
+- Real focus/blur behavior
+- Drag and drop
+- Cookie operations
+- Viewport-dependent behavior
+- Cross-browser validation
+
+## Vitest Browser Mode Setup
+
+```bash
+npm install -D @vitest/browser playwright
+```
+
+```javascript
+// vitest.config.js
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    browser: {
+      enabled: true,
+      name: 'chromium',
+      provider: 'playwright',
+    },
+  },
+})
+```
+
+```javascript
+// Button.browser.test.js
+import { render } from 'vitest-browser-vue'
+import Button from './Button.vue'
+
+test('has correct hover styling', async () => {
+  const { getByRole } = render(Button, { props: { label: 'Click me' } })
+
+  const button = getByRole('button')
+
+  // Check initial style
+  await expect.element(button).toHaveStyle({
+    backgroundColor: 'rgb(59, 130, 246)'  // blue
+  })
+})
+
+test('maintains focus after click', async () => {
+  const { getByRole } = render(Button)
+
+  const button = getByRole('button')
+  await button.click()
+
+  await expect.element(button).toHaveFocus()
+})
+```
+
+## Examples: What Each Runner Can/Cannot Test
+
+### Styles - Browser Required
+```javascript
+// Node runner: CANNOT verify actual CSS
+test('danger button has red background', () => {
+  const wrapper = mount(Button, { props: { variant: 'danger' } })
+  // This only checks class exists, not actual color
+  expect(wrapper.classes()).toContain('bg-red-500')
+})
+
+// Vitest Browser Mode: CAN verify computed styles
+test('danger button renders red', async () => {
+  const { getByRole } = render(Button, { props: { variant: 'danger' } })
+  await expect.element(getByRole('button')).toHaveStyle({
+    backgroundColor: 'rgb(239, 68, 68)'
+  })
+})
+```
+
+### Computed CSS Styles - Browser Required
+```javascript
+// Node runner: CANNOT get real computed styles
+test('button has correct padding', () => {
+  const wrapper = mount(Button)
+  // getComputedStyle returns empty/default values in jsdom
+  const style = window.getComputedStyle(wrapper.element)
+  // style.padding will be empty string, not actual computed value
+})
+
+// Vitest Browser Mode: Real computed styles
+test('button has correct padding', async () => {
+  const { getByRole } = render(Button)
+  const button = getByRole('button')
+
+  await expect.element(button).toHaveStyle({
+    padding: '12px 24px'
+  })
+})
+```
+
+### Native Events - Browser Required
+```javascript
+// Node runner: Synthetic events only
+test('handles drag and drop', async () => {
+  const wrapper = mount(DraggableList)
+  // trigger('dragstart') is synthetic - may not work as expected
+  await wrapper.find('.item').trigger('dragstart')
+})
+
+// Vitest Browser Mode: Real native events via userEvent
+import { userEvent } from '@vitest/browser/context'
+
+test('reorders items on drag', async () => {
+  const { getByTestId } = render(DraggableList)
+
+  const item = getByTestId('item-1')
+  const target = getByTestId('item-3')
+
+  await userEvent.dragAndDrop(item, target)
+
+  // Assert reordering
+})
+```
+
+## Recommended Testing Strategy
+
+```javascript
+// vitest.config.js - Separate test configurations
+
+export default defineConfig({
+  test: {
+    // Default: Node environment for speed
+    environment: 'happy-dom',
+
+    // Browser tests in separate directory
+    include: ['src/**/*.test.{js,ts}'],
+  },
+})
+
+// Run browser tests separately
+// npx vitest --browser.enabled
+```
+
+### Directory Structure
+```
+tests/
+├── unit/              # Fast node-based tests
+│   ├── Button.test.js
+│   └── useCounter.test.js
+├── component/         # Slower browser-based tests
+│   ├── Button.browser.test.js
+│   └── DragDrop.browser.test.js
+└── e2e/               # Full E2E tests (Playwright)
+    └── user-flow.spec.ts
+```
+
+## Reference
+- [Vue.js Testing - Component Testing](https://vuejs.org/guide/scaling-up/testing#component-testing)
+- [Vitest Browser Mode](https://vitest.dev/guide/browser.html)

package/skills/vue-testing-best-practices/reference/testing-component-blackbox-approach.md

@@ -0,0 +1,144 @@
+---
+title: Test Components Using Blackbox Approach - Focus on Behavior Not Implementation
+impact: HIGH
+impactDescription: Implementation-aware tests become brittle and break during refactoring, leading to high maintenance burden
+type: best-practice
+tags: [vue3, testing, component-testing, vitest, vue-test-utils, blackbox]
+---
+
+# Test Components Using Blackbox Approach - Focus on Behavior Not Implementation
+
+**Impact: HIGH** - Tests that rely on implementation details (internal state, private methods, component structure) break during refactoring even when functionality remains correct. This leads to false negatives and high test maintenance burden.
+
+Follow Kent C. Dodds' testing philosophy: "The more your tests resemble how your software is used, the more confidence they can give you."
+
+## Task Checklist
+
+- [ ] Test what the component does, not how it does it
+- [ ] Query elements by user-visible attributes (text, role, testid)
+- [ ] Simulate user interactions (click, type) rather than calling methods directly
+- [ ] Assert on rendered output, emitted events, and visible state changes
+- [ ] Avoid accessing component internal state or private methods
+- [ ] Use data-testid attributes for elements without semantic meaning
+
+**Incorrect:**
+```javascript
+import { mount } from '@vue/test-utils'
+import Counter from './Counter.vue'
+
+// BAD: Testing implementation details
+test('counter increments', async () => {
+  const wrapper = mount(Counter)
+
+  // Accessing internal state directly
+  expect(wrapper.vm.count).toBe(0)
+
+  // Calling internal method instead of simulating user action
+  wrapper.vm.increment()
+
+  // Checking internal state instead of visible output
+  expect(wrapper.vm.count).toBe(1)
+})
+
+// BAD: Testing component structure
+test('has increment button', () => {
+  const wrapper = mount(Counter)
+
+  // Testing implementation detail - what if button becomes an anchor?
+  expect(wrapper.find('button').exists()).toBe(true)
+})
+```
+
+**Correct:**
+```javascript
+import { mount } from '@vue/test-utils'
+import Counter from './Counter.vue'
+
+// CORRECT: Testing behavior like a user would
+test('counter displays updated value after clicking increment', async () => {
+  const wrapper = mount(Counter, {
+    props: { max: 10 }
+  })
+
+  // Assert initial visible state
+  expect(wrapper.find('[data-testid="counter-value"]').text()).toContain('0')
+
+  // Simulate user action
+  await wrapper.find('[data-testid="increment-button"]').trigger('click')
+
+  // Assert visible result
+  expect(wrapper.find('[data-testid="counter-value"]').text()).toContain('1')
+})
+
+// CORRECT: Testing emitted events (public API)
+test('emits change event with new value when incremented', async () => {
+  const wrapper = mount(Counter)
+
+  await wrapper.find('[data-testid="increment-button"]').trigger('click')
+
+  expect(wrapper.emitted('change')).toHaveLength(1)
+  expect(wrapper.emitted('change')[0]).toEqual([1])
+})
+```
+
+## Using @testing-library/vue for Better Blackbox Tests
+
+```javascript
+import { render, screen, fireEvent } from '@testing-library/vue'
+import Counter from './Counter.vue'
+
+// Testing Library encourages accessible, user-centric queries
+test('increments counter on button click', async () => {
+  render(Counter)
+
+  // Query by role - how screen readers see it
+  const button = screen.getByRole('button', { name: /increment/i })
+  const display = screen.getByText('0')
+
+  await fireEvent.click(button)
+
+  expect(screen.getByText('1')).toBeInTheDocument()
+})
+```
+
+## What to Test vs What Not to Test
+
+### DO Test (Public Interface)
+```javascript
+// Props affect rendered output
+test('shows title from props', () => {
+  const wrapper = mount(Card, {
+    props: { title: 'Hello World' }
+  })
+  expect(wrapper.text()).toContain('Hello World')
+})
+
+// Slots render correctly
+test('renders slot content', () => {
+  const wrapper = mount(Card, {
+    slots: { default: '<p>Slot content</p>' }
+  })
+  expect(wrapper.text()).toContain('Slot content')
+})
+
+// Emitted events
+test('emits close event when X clicked', async () => {
+  const wrapper = mount(Modal)
+  await wrapper.find('[data-testid="close-button"]').trigger('click')
+  expect(wrapper.emitted('close')).toBeTruthy()
+})
+```
+
+### DON'T Test (Implementation Details)
+```javascript
+// Don't test internal computed properties
+// Don't test internal methods
+// Don't test component options/setup internals
+// Don't test that specific child components are rendered (unless critical)
+// Don't rely exclusively on snapshot tests for correctness
+```
+
+## Reference
+- [Vue.js Testing Guide](https://vuejs.org/guide/scaling-up/testing)
+- [Vue Test Utils - Testing Philosophy](https://test-utils.vuejs.org/guide/)
+- [Testing Library Guiding Principles](https://testing-library.com/docs/guiding-principles)