devskill 2.0.2

package/skills/vue-testing-best-practices/reference/testing-composables-helper-wrapper.md

@@ -0,0 +1,238 @@
+---
+title: Test Complex Composables with Host Component Wrapper
+impact: MEDIUM
+impactDescription: Composables using lifecycle hooks or provide/inject fail when tested directly without a component context
+type: capability
+tags: [vue3, testing, composables, vitest, lifecycle-hooks, provide-inject]
+---
+
+# Test Complex Composables with Host Component Wrapper
+
+**Impact: MEDIUM** - Composables that use Vue lifecycle hooks (`onMounted`, `onUnmounted`) or dependency injection (`inject`) require a component context to function. Testing them directly will cause errors or incorrect behavior.
+
+Simple composables using only reactivity APIs can be tested directly. Complex composables need a helper function that creates a host component context.
+
+## Task Checklist
+
+- [ ] Identify if composable uses lifecycle hooks or inject
+- [ ] For simple composables (refs, computed only): test directly
+- [ ] For complex composables: use `withSetup` helper pattern
+- [ ] Clean up by unmounting the test app after each test
+- [ ] Use `app.provide()` to mock injected dependencies
+
+**Simple Composable - Test Directly:**
+```javascript
+// composables/useCounter.js
+import { ref, computed } from 'vue'
+
+export function useCounter(initialValue = 0) {
+  const count = ref(initialValue)
+  const doubled = computed(() => count.value * 2)
+  const increment = () => count.value++
+
+  return { count, doubled, increment }
+}
+```
+
+```javascript
+// useCounter.test.js
+import { describe, it, expect } from 'vitest'
+import { useCounter } from './useCounter'
+
+// CORRECT: Simple composable can be tested directly
+describe('useCounter', () => {
+  it('initializes with default value', () => {
+    const { count } = useCounter()
+    expect(count.value).toBe(0)
+  })
+
+  it('increments count', () => {
+    const { count, increment } = useCounter()
+    increment()
+    expect(count.value).toBe(1)
+  })
+
+  it('computes doubled value', () => {
+    const { count, doubled, increment } = useCounter(5)
+    expect(doubled.value).toBe(10)
+    increment()
+    expect(doubled.value).toBe(12)
+  })
+})
+```
+
+**Complex Composable - Use Host Wrapper:**
+```javascript
+// composables/useFetch.js
+import { ref, onMounted, onUnmounted, inject } from 'vue'
+
+export function useFetch(url) {
+  const data = ref(null)
+  const error = ref(null)
+  const loading = ref(true)
+  let controller = null
+
+  // Uses inject - needs component context
+  const apiClient = inject('apiClient')
+
+  // Uses lifecycle hooks - needs component context
+  onMounted(async () => {
+    controller = new AbortController()
+    try {
+      const response = await apiClient.get(url, { signal: controller.signal })
+      data.value = response.data
+    } catch (e) {
+      if (e.name !== 'AbortError') error.value = e
+    } finally {
+      loading.value = false
+    }
+  })
+
+  onUnmounted(() => {
+    controller?.abort()
+  })
+
+  return { data, error, loading }
+}
+```
+
+```javascript
+// test-utils.js
+import { createApp } from 'vue'
+
+/**
+ * Helper to test composables that need component context
+ */
+export function withSetup(composable) {
+  let result
+
+  const app = createApp({
+    setup() {
+      result = composable()
+      // Return a render function to suppress warnings
+      return () => {}
+    }
+  })
+
+  app.mount(document.createElement('div'))
+
+  return [result, app]
+}
+```
+
+```javascript
+// useFetch.test.js
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { flushPromises } from '@vue/test-utils'
+import { withSetup } from './test-utils'
+import { useFetch } from './useFetch'
+
+describe('useFetch', () => {
+  let app
+  const mockApiClient = {
+    get: vi.fn()
+  }
+
+  afterEach(() => {
+    // IMPORTANT: Clean up to trigger onUnmounted
+    app?.unmount()
+  })
+
+  it('fetches data on mount', async () => {
+    mockApiClient.get.mockResolvedValue({ data: { id: 1, name: 'Test' } })
+
+    const [result, testApp] = withSetup(() => useFetch('/api/test'))
+    app = testApp
+
+    // Provide mocked dependency
+    app.provide('apiClient', mockApiClient)
+
+    // Wait for async operations
+    await flushPromises()
+
+    expect(result.data.value).toEqual({ id: 1, name: 'Test' })
+    expect(result.loading.value).toBe(false)
+    expect(result.error.value).toBeNull()
+  })
+
+  it('handles errors', async () => {
+    const testError = new Error('Network error')
+    mockApiClient.get.mockRejectedValue(testError)
+
+    const [result, testApp] = withSetup(() => useFetch('/api/test'))
+    app = testApp
+    app.provide('apiClient', mockApiClient)
+
+    await flushPromises()
+
+    expect(result.error.value).toBe(testError)
+    expect(result.data.value).toBeNull()
+  })
+})
+```
+
+## Enhanced withSetup Helper with Provide Support
+```javascript
+// test-utils.js
+export function withSetup(composable, options = {}) {
+  let result
+
+  const app = createApp({
+    setup() {
+      result = composable()
+      return () => {}
+    }
+  })
+
+  // Apply global provides before mounting
+  if (options.provide) {
+    Object.entries(options.provide).forEach(([key, value]) => {
+      app.provide(key, value)
+    })
+  }
+
+  app.mount(document.createElement('div'))
+
+  return [result, app]
+}
+
+// Usage
+const [result, app] = withSetup(() => useMyComposable(), {
+  provide: {
+    apiClient: mockApiClient,
+    currentUser: { id: 1, name: 'Test User' }
+  }
+})
+```
+
+## Testing with @vue/test-utils mount
+```javascript
+import { mount } from '@vue/test-utils'
+import { defineComponent } from 'vue'
+import { useFetch } from './useFetch'
+
+test('useFetch in component context', async () => {
+  const TestComponent = defineComponent({
+    setup() {
+      const { data, loading } = useFetch('/api/users')
+      return { data, loading }
+    },
+    template: '<div>{{ loading ? "Loading..." : data }}</div>'
+  })
+
+  const wrapper = mount(TestComponent, {
+    global: {
+      provide: {
+        apiClient: mockApiClient
+      }
+    }
+  })
+
+  await flushPromises()
+  expect(wrapper.text()).toContain('Test data')
+})
+```
+
+## Reference
+- [Vue.js Testing Guide - Testing Composables](https://vuejs.org/guide/scaling-up/testing#testing-composables)
+- [Vue Test Utils - Mounting Components](https://test-utils.vuejs.org/guide/)

package/skills/vue-testing-best-practices/reference/testing-e2e-playwright-recommended.md

@@ -0,0 +1,242 @@
+---
+title: Use Playwright for E2E Testing - Cross-Browser Support and Better DX
+impact: MEDIUM
+impactDescription: Cypress has browser limitations and some features require paid subscriptions
+type: best-practice
+tags: [vue3, testing, e2e, playwright, cypress, end-to-end]
+---
+
+# Use Playwright for E2E Testing - Cross-Browser Support and Better DX
+
+**Impact: MEDIUM** - Playwright offers superior cross-browser testing (Chromium, WebKit, Firefox), excellent debugging tools, and is fully open source. Cypress has limitations with WebKit support and requires paid subscriptions for some features.
+
+Use Playwright for new E2E testing setups. Consider Cypress if team already has expertise or for its visual debugging UI.
+
+## Task Checklist
+
+- [ ] Install Playwright with browsers for your target platforms
+- [ ] Configure for Vue dev server integration
+- [ ] Set up projects for different browsers
+- [ ] Use locator strategies that match component test patterns
+- [ ] Configure CI for parallel test execution
+- [ ] Use trace and screenshot features for debugging
+
+## Quick Setup
+
+```bash
+# Install Playwright
+npm init playwright@latest
+
+# This will create:
+# - playwright.config.ts
+# - tests/ directory
+# - tests-examples/ directory
+```
+
+**playwright.config.ts:**
+```typescript
+import { defineConfig, devices } from '@playwright/test'
+
+export default defineConfig({
+  testDir: './e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: 'html',
+
+  use: {
+    // Base URL for navigation
+    baseURL: 'http://localhost:5173',
+    // Capture trace on first retry
+    trace: 'on-first-retry',
+    // Screenshot on failure
+    screenshot: 'only-on-failure',
+  },
+
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+    },
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] },
+    },
+    // Mobile viewports
+    {
+      name: 'Mobile Chrome',
+      use: { ...devices['Pixel 5'] },
+    },
+  ],
+
+  // Run local dev server before tests
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:5173',
+    reuseExistingServer: !process.env.CI,
+  },
+})
+```
+
+## E2E Test Example
+
+```typescript
+// e2e/user-flow.spec.ts
+import { test, expect } from '@playwright/test'
+
+test.describe('User Authentication', () => {
+  test('user can log in and see dashboard', async ({ page }) => {
+    // Navigate to login
+    await page.goto('/login')
+
+    // Fill login form
+    await page.getByLabel('Email').fill('user@example.com')
+    await page.getByLabel('Password').fill('password123')
+    await page.getByRole('button', { name: 'Sign In' }).click()
+
+    // Verify redirect to dashboard
+    await expect(page).toHaveURL('/dashboard')
+    await expect(page.getByRole('heading', { name: 'Welcome' })).toBeVisible()
+  })
+
+  test('shows error for invalid credentials', async ({ page }) => {
+    await page.goto('/login')
+
+    await page.getByLabel('Email').fill('wrong@example.com')
+    await page.getByLabel('Password').fill('wrongpassword')
+    await page.getByRole('button', { name: 'Sign In' }).click()
+
+    await expect(page.getByRole('alert')).toContainText('Invalid credentials')
+    await expect(page).toHaveURL('/login')
+  })
+})
+```
+
+## Playwright vs Cypress Comparison
+
+| Feature | Playwright | Cypress |
+|---------|------------|---------|
+| Browsers | Chromium, Firefox, WebKit | Chromium, Firefox, Electron (WebKit experimental) |
+| Cross-browser | Full support | Limited |
+| Parallelization | Built-in | Requires Cypress Cloud |
+| Open source | Fully | Core only |
+| Mobile testing | Device emulation | Limited |
+| Debugging | Inspector, trace viewer | Time-travel UI |
+| API testing | Built-in | Plugin required |
+| Iframes | Full support | Limited |
+
+## Testing Vue Components with Data-Testid
+
+```typescript
+// e2e/product-list.spec.ts
+import { test, expect } from '@playwright/test'
+
+test('user can add product to cart', async ({ page }) => {
+  await page.goto('/products')
+
+  // Use data-testid for reliable selectors
+  await page.getByTestId('product-card').first().click()
+
+  // Verify product detail page
+  await expect(page.getByTestId('product-title')).toBeVisible()
+
+  // Add to cart
+  await page.getByTestId('add-to-cart-button').click()
+
+  // Verify cart updated
+  await expect(page.getByTestId('cart-count')).toHaveText('1')
+})
+```
+
+## Page Object Pattern for Vue Apps
+
+```typescript
+// e2e/pages/LoginPage.ts
+import { Page, Locator } from '@playwright/test'
+
+export class LoginPage {
+  readonly page: Page
+  readonly emailInput: Locator
+  readonly passwordInput: Locator
+  readonly submitButton: Locator
+  readonly errorMessage: Locator
+
+  constructor(page: Page) {
+    this.page = page
+    this.emailInput = page.getByLabel('Email')
+    this.passwordInput = page.getByLabel('Password')
+    this.submitButton = page.getByRole('button', { name: 'Sign In' })
+    this.errorMessage = page.getByRole('alert')
+  }
+
+  async goto() {
+    await this.page.goto('/login')
+  }
+
+  async login(email: string, password: string) {
+    await this.emailInput.fill(email)
+    await this.passwordInput.fill(password)
+    await this.submitButton.click()
+  }
+}
+```
+
+```typescript
+// e2e/auth.spec.ts
+import { test, expect } from '@playwright/test'
+import { LoginPage } from './pages/LoginPage'
+
+test('successful login', async ({ page }) => {
+  const loginPage = new LoginPage(page)
+  await loginPage.goto()
+  await loginPage.login('user@example.com', 'password123')
+
+  await expect(page).toHaveURL('/dashboard')
+})
+```
+
+## Visual Regression Testing
+
+```typescript
+test('homepage visual regression', async ({ page }) => {
+  await page.goto('/')
+
+  // Full page screenshot comparison
+  await expect(page).toHaveScreenshot('homepage.png')
+
+  // Element-specific screenshot
+  await expect(page.getByTestId('hero-section')).toHaveScreenshot('hero.png')
+})
+```
+
+## Running Tests
+
+```bash
+# Run all tests
+npx playwright test
+
+# Run in headed mode (see browser)
+npx playwright test --headed
+
+# Run specific file
+npx playwright test e2e/auth.spec.ts
+
+# Run in specific browser
+npx playwright test --project=chromium
+
+# Debug mode
+npx playwright test --debug
+
+# Generate test from actions
+npx playwright codegen localhost:5173
+```
+
+## Reference
+- [Playwright Documentation](https://playwright.dev/)
+- [Vue.js E2E Testing Recommendations](https://vuejs.org/guide/scaling-up/testing#e2e-testing)
+- [Playwright Best Practices](https://playwright.dev/docs/best-practices)

package/skills/vue-testing-best-practices/reference/testing-no-snapshot-only.md

@@ -0,0 +1,197 @@
+---
+title: Avoid Snapshot-Only Tests - They Don't Prove Correctness
+impact: MEDIUM
+impactDescription: Snapshot tests verify structure but not functionality, leading to false confidence and brittle tests
+type: best-practice
+tags: [vue3, testing, snapshot, vitest, vue-test-utils, anti-pattern]
+---
+
+# Avoid Snapshot-Only Tests - They Don't Prove Correctness
+
+**Impact: MEDIUM** - Snapshot tests only verify that HTML structure hasn't changed - they don't verify that the component works correctly. Relying exclusively on snapshots leads to false confidence and tests that break on any refactoring, even when functionality is preserved.
+
+Use snapshots sparingly for regression detection. Prefer behavioral assertions that test what the component does.
+
+## Task Checklist
+
+- [ ] Don't use snapshots as the only assertion for component behavior
+- [ ] Use snapshots for regression detection on stable UI components
+- [ ] Always pair snapshots with behavioral assertions
+- [ ] Keep snapshots small and focused (avoid full component snapshots)
+- [ ] Review snapshot diffs carefully - don't blindly update
+- [ ] Consider inline snapshots for small, critical structures
+
+**Incorrect:**
+```javascript
+import { mount } from '@vue/test-utils'
+import UserCard from './UserCard.vue'
+
+// BAD: Snapshot-only test proves nothing about functionality
+test('UserCard renders correctly', () => {
+  const wrapper = mount(UserCard, {
+    props: { user: { name: 'John', email: 'john@example.com' } }
+  })
+
+  expect(wrapper.html()).toMatchSnapshot()
+})
+
+// This test passes even if:
+// - The email isn't clickable
+// - The avatar doesn't load
+// - User actions are completely broken
+// - Accessibility is broken
+```
+
+**Correct:**
+```javascript
+import { mount } from '@vue/test-utils'
+import UserCard from './UserCard.vue'
+
+// CORRECT: Test actual behavior
+test('UserCard displays user information', () => {
+  const wrapper = mount(UserCard, {
+    props: { user: { name: 'John', email: 'john@example.com' } }
+  })
+
+  expect(wrapper.find('[data-testid="user-name"]').text()).toBe('John')
+  expect(wrapper.find('[data-testid="user-email"]').text()).toBe('john@example.com')
+})
+
+test('UserCard email link is clickable', async () => {
+  const wrapper = mount(UserCard, {
+    props: { user: { name: 'John', email: 'john@example.com' } }
+  })
+
+  const emailLink = wrapper.find('a[href^="mailto:"]')
+  expect(emailLink.exists()).toBe(true)
+  expect(emailLink.attributes('href')).toBe('mailto:john@example.com')
+})
+
+test('UserCard emits select event when clicked', async () => {
+  const wrapper = mount(UserCard, {
+    props: { user: { id: 1, name: 'John' } }
+  })
+
+  await wrapper.trigger('click')
+
+  expect(wrapper.emitted('select')).toBeTruthy()
+  expect(wrapper.emitted('select')[0]).toEqual([{ id: 1, name: 'John' }])
+})
+```
+
+## When Snapshots ARE Useful
+
+### Regression Detection for Stable Components
+```javascript
+// ACCEPTABLE: Snapshot as additional check, not the only check
+test('ErrorBoundary renders error message', () => {
+  const wrapper = mount(ErrorBoundary, {
+    props: { error: new Error('Something went wrong') }
+  })
+
+  // Primary assertions - verify behavior
+  expect(wrapper.find('.error-title').text()).toBe('Error')
+  expect(wrapper.find('.error-message').text()).toContain('Something went wrong')
+
+  // Secondary snapshot - catches unexpected structural changes
+  expect(wrapper.find('.error-container').html()).toMatchSnapshot()
+})
+```
+
+### Inline Snapshots for Small Structures
+```javascript
+// ACCEPTABLE: Inline snapshot for small, critical structure
+test('generates correct list markup', () => {
+  const wrapper = mount(ListItem, { props: { item: 'Test' } })
+
+  expect(wrapper.html()).toMatchInlineSnapshot(`
+    "<li class="list-item">Test</li>"
+  `)
+})
+```
+
+### Complex SVG or Icon Output
+```javascript
+// ACCEPTABLE: Snapshot for complex generated content
+test('renders correct chart SVG', () => {
+  const wrapper = mount(PieChart, {
+    props: { data: [30, 40, 30] }
+  })
+
+  // Verify key behavior
+  expect(wrapper.findAll('path').length).toBe(3)
+
+  // Snapshot for full SVG structure
+  expect(wrapper.find('svg').html()).toMatchSnapshot()
+})
+```
+
+## Better Alternatives to Snapshots
+
+### Test Specific Elements
+```javascript
+// Instead of snapshotting entire component
+test('renders product with all required fields', () => {
+  const wrapper = mount(ProductCard, {
+    props: { product: { name: 'Widget', price: 9.99, inStock: true } }
+  })
+
+  expect(wrapper.find('.product-name').text()).toBe('Widget')
+  expect(wrapper.find('.product-price').text()).toContain('9.99')
+  expect(wrapper.find('.in-stock-badge').exists()).toBe(true)
+})
+```
+
+### Test CSS Classes for Styling
+```javascript
+test('applies danger styling for errors', () => {
+  const wrapper = mount(Alert, {
+    props: { type: 'error', message: 'Failed!' }
+  })
+
+  expect(wrapper.classes()).toContain('alert-danger')
+  expect(wrapper.find('.alert-icon').classes()).toContain('icon-error')
+})
+```
+
+### Use Testing Library Queries
+```javascript
+import { render, screen } from '@testing-library/vue'
+
+test('form has accessible labels', () => {
+  render(LoginForm)
+
+  // Testing Library queries verify accessibility
+  expect(screen.getByLabelText('Email')).toBeInTheDocument()
+  expect(screen.getByLabelText('Password')).toBeInTheDocument()
+  expect(screen.getByRole('button', { name: 'Sign In' })).toBeInTheDocument()
+})
+```
+
+## Snapshot Anti-Patterns
+
+```javascript
+// ANTI-PATTERN: Giant component snapshot
+test('page renders', () => {
+  const wrapper = mount(EntirePageComponent)
+  expect(wrapper.html()).toMatchSnapshot()  // 500+ lines of HTML
+})
+
+// ANTI-PATTERN: Snapshot with dynamic content
+test('shows current date', () => {
+  const wrapper = mount(DateDisplay)
+  expect(wrapper.html()).toMatchSnapshot()  // Fails every day!
+})
+
+// ANTI-PATTERN: Snapshot after every test
+test('button works', async () => {
+  const wrapper = mount(Counter)
+  await wrapper.find('button').trigger('click')
+  expect(wrapper.html()).toMatchSnapshot()  // Redundant
+})
+```
+
+## Reference
+- [Vue.js Testing Guide - What Not to Test](https://vuejs.org/guide/scaling-up/testing)
+- [Effective Snapshot Testing](https://kentcdodds.com/blog/effective-snapshot-testing)
+- [Vitest Snapshot Testing](https://vitest.dev/guide/snapshot.html)