---

name: vue-development description: Vue 3 and Nuxt 3 development with TDD workflow, QA gates, and E2E test generation. Enforces unit testing before implementation, generates Playwright E2E tests from Gherkin acceptance criteria, and produces JSON reports.

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:

Copy1. 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: User Story Format

This skill accepts user stories with Gherkin acceptance criteria:

Copy## 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}

CopyGiven {precondition}
When {invalid action}
Then {error handling}

Copy
**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:

Copynpm run test -- MyComponent.spec.ts

Step 3: Implement Component

Write the minimal code to make tests pass:

Copy<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

Copynpm 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):

• Props typed with TypeScript
• Emits typed with defineEmits<{...}>()
• No any types
• Computed for derived state
• Single responsibility
• Tests cover all behaviors

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

Copy// 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 "user@example.com"
    await page.fill('[name="email"]', 'user@example.com');

    // 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 "user@example.com"
    await page.fill('[name="email"]', 'user@example.com');

    // 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

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 E2E Tests

Execute the generated Playwright tests to validate acceptance criteria.

Run Tests

Copy# Run specific test file
npx playwright test tests/e2e/user-login.spec.ts

# Run all E2E tests
npx playwright test tests/e2e/

# Run with UI mode for debugging
npx playwright test tests/e2e/user-login.spec.ts --ui

Verify Results

All acceptance criteria must pass:

CopyRunning 2 tests using 1 worker

  ✓ US-001: User Login › AC1: Successful login (2.1s)
  ✓ US-001: User Login › AC2: Invalid password (1.8s)

  2 passed (4.2s)

Handle Failures

If tests fail:

1. Review the error - Check which AC failed and why
2. Fix the implementation - Update component/page code
3. Re-run tests - Verify fix works
4. Do NOT modify the test unless the AC was wrong

CopyIf AC fails → Fix implementation, NOT the test
If AC is wrong → Update user story first, then regenerate test

Step 8: Generate Report

REQUIRED: Create a JSON report with E2E validation results.

Location: .qa-reports/{uuid}.vue-development-skill.json

Generate a UUID and write the report:

Copy{
  "id": "generated-uuid-here",
  "skill": "vue-development",
  "timestamp": "2025-12-01T10:30:00Z",
  "task_description": "Created MyComponent button with click handling",

  "user_story": {
    "id": "US-001",
    "title": "User Login",
    "persona": "registered user",
    "goal": "to login with my credentials",
    "benefit": "I can access my account"
  },

  "files": {
    "created": ["src/components/MyComponent.vue"],
    "modified": [],
    "test_files": ["src/components/__tests__/MyComponent.spec.ts"],
    "e2e_test_files": ["tests/e2e/us-001-user-login.spec.ts"]
  },

  "tdd": {
    "tests_written_first": true,
    "test_command": "npm run test -- MyComponent.spec.ts",
    "tests_passing": true,
    "coverage_estimate": "high"
  },

  "qa": {
    "score": 9.0,
    "status": "PASS",
    "checklist": {
      "component_quality": { "passed": 5, "total": 5, "issues": [] },
      "reactivity": { "passed": 4, "total": 4, "issues": [] },
      "composables": { "passed": 0, "total": 0, "issues": ["N/A"] },
      "nuxt_specific": {
        "passed": 0,
        "total": 0,
        "issues": ["N/A - plain Vue"]
      },
      "typescript": { "passed": 4, "total": 4, "issues": [] },
      "unit_tests": { "passed": 6, "total": 6, "issues": [] }
    }
  },

  "e2e_validation": {
    "test_file": "tests/e2e/us-001-user-login.spec.ts",
    "test_command": "npx playwright test tests/e2e/us-001-user-login.spec.ts",
    "executed": true,
    "acceptance_criteria": [
      {
        "id": "AC1",
        "title": "Successful login",
        "gherkin": "Given I am on login page\nWhen I fill credentials\nThen I see dashboard",
        "status": "PASS"
      },
      {
        "id": "AC2",
        "title": "Invalid password",
        "gherkin": "Given I am on login page\nWhen I enter wrong password\nThen I see error",
        "status": "PASS"
      }
    ],
    "passed": 2,
    "failed": 0,
    "status": "PASS"
  },

  "completion": {
    "unit_tests": "PASS",
    "qa_checklist": "PASS",
    "e2e_validation": "PASS",
    "overall": "COMPLETE"
  }
}

Quality Thresholds

Formula: score = (checks_passed / total_applicable_checks) × 10

File References

• QA Checklist: See qa/vue-checklist.md for full criteria
• Report Schema: See qa/report-template.json for JSON structure
• TDD Guide: See tdd/workflow.md for detailed process
• Testing Patterns: See tdd/testing-patterns.md for Vitest examples
• Vue Patterns: See patterns/composition-api.md
• Nuxt Patterns: See patterns/nuxt3.md
• TypeScript: See patterns/typescript.md
• Debugging: See debugging/common-issues.md
• E2E Patterns: See e2e/playwright-patterns.md for Gherkin-to-Playwright mapping
• Acceptance Criteria: See e2e/acceptance-criteria.md for parsing user stories

Important Rules

1. NEVER skip tests - Write tests before implementation
2. NEVER skip E2E validation - Validate all acceptance criteria with Playwright
3. NEVER skip the report - Include E2E results in report
4. NEVER leave tests failing - All unit tests AND E2E must pass
5. ALWAYS use TypeScript - No JavaScript, no any
6. ALWAYS follow Composition API - No Options API
7. ALWAYS validate against Gherkin AC - If user story provided, all AC must pass