vue-development

What this skill does

# Vue Development Skill

This skill guides development of Vue 3 and Nuxt 3 applications using a **test-driven development** approach with **quality assurance gates** and **E2E test generation from acceptance criteria**.

## When This Skill Activates

Use this skill when:
- Creating or modifying `.vue` files
- Writing composables (`use*.ts`)
- Working with Nuxt-specific files (`pages/`, `layouts/`, `middleware/`, `composables/`)
- User mentions Vue, Nuxt, or component development
- Building reactive UI components
- **Implementing user stories with Gherkin acceptance criteria**

## Core Workflow: TDD + QA + E2E

**ALWAYS follow this workflow:**

```
1. UNDERSTAND  → Parse user story + Gherkin acceptance criteria
2. TEST FIRST  → Write failing unit tests (Vitest + Vue Test Utils)
3. IMPLEMENT   → Write minimal code to pass tests
4. REFACTOR    → Clean up while keeping tests green
5. QA CHECK    → Validate against Vue checklist (see qa/vue-checklist.md)
6. E2E WRITE   → Generate Playwright test files from Gherkin AC
7. E2E RUN     → Execute tests and verify all AC pass
8. REPORT      → Generate JSON report with E2E results
```

---

## Input handling

Follow shared foundation §7 — interview mode. If the user story is missing or incomplete (missing narrative, acceptance criteria, or technical constraints), enter interview mode to gather the missing elements before proceeding. Skill-specific dimensions:

| Dimension | Required |
|---|---|
| Narrative (As a/I want/So that) | Yes |
| Acceptance criteria (Gherkin Given/When/Then) | Yes |
| Technical constraints | No (inferred from codebase) |
| Component scope (what to build) | Yes |

## Input: User Story Format

This skill accepts user stories with Gherkin acceptance criteria:

```markdown
## US-001: {Story Title}

> **As a** {persona},
> **I want** {goal},
> **So that** {benefit}.

### Acceptance Criteria

#### AC1: {Happy Path}

```gherkin
Given {precondition}
When {action}
Then {expected result}
```

#### AC2: {Error Scenario}

```gherkin
Given {precondition}
When {invalid action}
Then {error handling}
```
```

**See:** `e2e/acceptance-criteria.md` for detailed parsing guide.

## Step-by-Step Instructions

### Step 1: Understand Requirements

Before writing any code:
- **Parse the user story** to understand persona, goal, and benefit
- **Extract acceptance criteria** (Gherkin Given/When/Then)
- Identify props, emits, and slots needed
- Determine reactive state requirements
- Map acceptance criteria to testable behaviors

### Step 2: Write Tests First

**Create test file BEFORE implementation:**

```typescript
// src/components/__tests__/MyComponent.spec.ts
import { describe, it, expect } from 'vitest'
import { mount } from '@vue/test-utils'
import MyComponent from '../MyComponent.vue'

describe('MyComponent', () => {
  it('renders with default props', () => {
    const wrapper = mount(MyComponent)
    expect(wrapper.exists()).toBe(true)
  })

  it('displays label prop correctly', () => {
    const wrapper = mount(MyComponent, {
      props: { label: 'Click me' }
    })
    expect(wrapper.text()).toContain('Click me')
  })

  it('emits click event when clicked', async () => {
    const wrapper = mount(MyComponent)
    await wrapper.trigger('click')
    expect(wrapper.emitted('click')).toBeTruthy()
  })
})
```

**Run tests to confirm they fail:**
```bash
npm run test -- MyComponent.spec.ts
```

### Step 3: Implement Component

Write the **minimal code** to make tests pass:

```vue
<script setup lang="ts">
interface Props {
  label?: string
}

const props = withDefaults(defineProps<Props>(), {
  label: 'Button'
})

const emit = defineEmits<{
  click: []
}>()

function handleClick() {
  emit('click')
}
</script>

<template>
  <button @click="handleClick">
    {{ label }}
  </button>
</template>
```

### Step 4: Verify Tests Pass

```bash
npm run test -- MyComponent.spec.ts
```

All tests must be green before proceeding.

### Step 5: QA Validation

Go through the **Vue QA Checklist** (see `qa/vue-checklist.md`). The checklist is structured on the **ISO/IEC 25010:2023 product quality model** — all 9 characteristics, one item per sub-characteristic (~40 items). Validate every applicable item and mark genuinely irrelevant items **N/A** (N/A items are excluded from scoring, never counted as failures).

The 9 characteristics:

| # | Characteristic | Front-end focus |
|---|---|---|
| 1 | Functional Suitability | AC→test coverage, correctness, no scope creep |
| 2 | Performance Efficiency | computed memoization, cleanup, list capacity |
| 3 | Compatibility | scoped styles, typed public contract |
| 4 | Interaction Capability | keyboard, WCAG 2.2 AA, feedback states |
| 5 | Reliability | edge cases, SSR/hydration, error handling, recovery |
| 6 | Security | no secrets, no XSS sinks, auth guards, input hardening |
| 7 | Maintainability | SRP, composables, typing, no prop mutation, TDD |
| 8 | Flexibility | responsive/tokens, scalability, replaceability |
| 9 | Safety | confirm destructive actions, fail-safe, boundary validation |

Score per characteristic and overall: `score = (items_passed / total_applicable_items) × 10`.

### Step 6: Write E2E Test Files

**Generate Playwright test files from Gherkin acceptance criteria.**

For each user story, create a test file:

**Location:** `tests/e2e/{feature-slug}.spec.ts`

#### Test File Structure

```typescript
// tests/e2e/user-login.spec.ts
import { test, expect } from '@playwright/test'

/**
 * US-001: User Login
 * As a registered user, I want to login with my credentials,
 * so that I can access my account.
 */
test.describe('US-001: User Login', () => {

  test('AC1: Successful login', async ({ page }) => {
    // Given I am on the login page
    await page.goto('/login')

    // When I fill "email" with "[email protected]"
    await page.fill('[name="email"]', '[email protected]')

    // And I fill "password" with "password123"
    await page.fill('[name="password"]', 'password123')

    // And I click "Login"
    await page.click('button:has-text("Login")')

    // Then I am redirected to the dashboard
    await expect(page).toHaveURL(/dashboard/)

    // And I see "Welcome back"
    await expect(page.locator('text=Welcome back')).toBeVisible()
  })

  test('AC2: Invalid password', async ({ page }) => {
    // Given I am on the login page
    await page.goto('/login')

    // When I fill "email" with "[email protected]"
    await page.fill('[name="email"]', '[email protected]')

    // And I fill "password" with "wrong"
    await page.fill('[name="password"]', 'wrong')

    // And I click "Login"
    await page.click('button:has-text("Login")')

    // Then I see "Invalid credentials"
    await expect(page.locator('text=Invalid credentials')).toBeVisible()
  })

})
```

#### Gherkin to Playwright Mapping

| Gherkin | Playwright Code |
|---------|-----------------|
| `Given I am on "{url}"` | `await page.goto('{url}')` |
| `When I click "{text}"` | `await page.click('text={text}')` |
| `When I click the "{selector}" button` | `await page.click('{selector}')` |
| `When I fill "{field}" with "{value}"` | `await page.fill('[name="{field}"]', '{value}')` |
| `When I select "{option}" from "{field}"` | `await page.selectOption('[name="{field}"]', '{option}')` |
| `When I press "{key}"` | `await page.keyboard.press('{key}')` |
| `Then I see "{text}"` | `await expect(page.locator('text={text}')).toBeVisible()` |
| `Then I am redirected to "{url}"` | `await expect(page).toHaveURL(/{url}/)` |
| `Then the "{element}" is visible` | `await expect(page.locator('{element}')).toBeVisible()` |
| `Then the "{element}" is not visible` | `await expect(page.locator('{element}')).not.toBeVisible()` |

#### File Naming Convention

- Story ID in filename: `{story-id}-{feature-slug}.spec.ts`
- Examples:
  - `us-001-user-login.spec.ts`
  - `us-042-password-reset.spec.ts`
  - `us-103-checkout-flow.spec.ts`

**See:** `e2e/playwright-patterns.md` for complete mapping reference.

### Step 7: Run