symfonia-ai-tools 1.0.0

package/templates/packs/vitest/_ai/instructions/vitest.instructions.md

@@ -0,0 +1,688 @@
+---
+applyTo: "**/*.test.ts,**/*.spec.ts"
+---
+
+# VITEST Testing Instructions
+
+## Table of Contents
+
+1. [Test Structure and Organization](#test-structure-and-organization)
+2. [Test Naming and Descriptions](#test-naming-and-descriptions)
+3. [Test Setup and Configuration](#test-setup-and-configuration)
+4. [Component Testing Patterns](#component-testing-patterns)
+5. [Test Coverage Requirements](#test-coverage-requirements)
+6. [Performance and Best Practices](#performance-and-best-practices)
+7. [Mocking and Stubbing](#mocking-and-stubbing)
+8. [Accessibility Testing](#accessibility-testing)
+9. [State and Event Testing](#state-and-event-testing)
+10. [Test Documentation](#test-documentation)
+
+---
+
+## Test Structure and Organization
+
+### File Organization
+- Place test files next to the component: `ComponentName.test.ts`
+- Use descriptive test file names: `InputText.test.ts`, `Button.test.ts`
+- Group related tests in `describe` blocks
+- Use nested `describe` blocks for logical grouping
+
+### Test Structure Template
+```typescript
+import { mount, VueWrapper } from '@vue/test-utils';
+import { beforeEach, describe, expect, it } from 'vitest';
+import ComponentName from './ComponentName.vue';
+
+describe('ComponentName Component', () => {
+    let wrapper: VueWrapper<InstanceType<typeof ComponentName>>;
+
+    beforeEach(() => {
+        wrapper = mount(ComponentName, {
+            props: {
+                // Required props only
+                dataTestId: 'test-component',
+            },
+        });
+    });
+
+    describe('Basic Rendering', () => {
+        // Basic rendering tests
+    });
+
+    describe('Props Testing', () => {
+        // Props validation tests
+    });
+
+    describe('States', () => {
+        // State-based tests (disabled, error, loading, etc.)
+    });
+
+    describe('Event Handling', () => {
+        // Event emission and handling tests
+    });
+
+    describe('Accessibility', () => {
+        // Accessibility tests
+    });
+
+    describe('Edge Cases', () => {
+        // Edge case and error handling tests
+    });
+
+    describe('Component Integration', () => {
+        // Complex integration tests
+    });
+});
+```
+
+---
+
+## Test Naming and Descriptions
+
+### Test Naming Conventions
+- Use descriptive test names that explain the expected behavior
+- Start with "should" for behavior descriptions
+- Use present tense: "should render correctly" not "should have rendered"
+- Be specific about conditions: "should be disabled when disabled prop is true"
+
+### Good Test Names Examples
+```typescript
+it('should render input element', () => {});
+it('should have correct name attribute', () => {});
+it('should be disabled when disabled prop is true', () => {});
+it('should emit click event when clicked', () => {});
+it('should handle null modelValue gracefully', () => {});
+it('should apply error class when error prop is true', () => {});
+```
+
+### Bad Test Names Examples
+```typescript
+it('works', () => {}); // Too vague
+it('test input', () => {}); // Not descriptive
+it('should have rendered', () => {}); // Past tense
+it('input test', () => {}); // Not a sentence
+```
+
+---
+
+## Test Setup and Configuration
+
+### Required Imports
+```typescript
+import { mount, VueWrapper } from '@vue/test-utils';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { nextTick } from 'vue'; // When needed for async operations
+```
+
+### Component Mounting
+- Always provide required props in `beforeEach`
+- Use `dataTestId` for test identification
+- Set up minimal required props only
+- Use `VueWrapper<InstanceType<typeof Component>>` for type safety
+
+### Test Configuration
+```typescript
+beforeEach(() => {
+    wrapper = mount(ComponentName, {
+        props: {
+            // Only required props
+            name: 'test-component',
+            dataTestId: 'test-component',
+        },
+        // Add slots if needed
+        slots: {
+            default: 'Test Content',
+        },
+        // Add global plugins if needed
+        global: {
+            plugins: [i18n, router],
+        },
+    });
+});
+```
+
+---
+
+## Component Testing Patterns
+
+### Basic Rendering Tests
+Test fundamental component structure and attributes:
+```typescript
+describe('Basic Rendering', () => {
+    it('should render main element', () => {
+        expect(wrapper.element.tagName).toBe('BUTTON');
+    });
+
+    it('should have correct data-testid attribute', () => {
+        expect(wrapper.attributes('data-testid')).toBe('test-button');
+    });
+
+    it('should have base CSS class', () => {
+        expect(wrapper.classes()).toContain('button');
+    });
+});
+```
+
+### Props Testing
+Test all component props systematically:
+```typescript
+describe('Props Testing', () => {
+    it('should set type attribute correctly', async () => {
+        await wrapper.setProps({ type: 'email' });
+        const input = wrapper.find('input');
+        expect(input.attributes('type')).toBe('email');
+    });
+
+    it('should default to text type', () => {
+        const input = wrapper.find('input');
+        expect(input.attributes('type')).toBe('text');
+    });
+
+    it('should handle null values gracefully', async () => {
+        await wrapper.setProps({ icon: null });
+        expect(wrapper.find('.icon').exists()).toBe(false);
+    });
+});
+```
+
+### State Testing
+Test component states (disabled, error, loading, etc.):
+```typescript
+describe('States', () => {
+    it('should be disabled when disabled prop is true', async () => {
+        await wrapper.setProps({ disabled: true });
+        expect(wrapper.attributes('disabled')).toBeDefined();
+        expect(wrapper.classes()).toContain('is-disabled');
+    });
+
+    it('should have error class when error prop is true', async () => {
+        await wrapper.setProps({ error: true });
+        expect(wrapper.classes()).toContain('is-error');
+    });
+});
+```
+
+### Event Testing
+Test event emission and handling:
+```typescript
+describe('Event Handling', () => {
+    it('should emit click event when clicked', async () => {
+        await wrapper.trigger('click');
+        expect(wrapper.emitted('click')).toBeTruthy();
+        expect(wrapper.emitted('click')).toHaveLength(1);
+    });
+
+    it('should not emit click event when disabled', async () => {
+        await wrapper.setProps({ disabled: true });
+        await wrapper.trigger('click');
+        expect(wrapper.emitted('click')).toBeFalsy();
+    });
+});
+```
+
+---
+
+## Test Coverage Requirements
+
+### Required Test Categories
+Every component must have tests for:
+
+1. **Basic Rendering** - Element structure, attributes, classes
+2. **Props Testing** - All props, default values, null handling
+3. **States** - Disabled, error, loading, required states
+4. **Event Handling** - Click, input, change events
+5. **Accessibility** - ARIA attributes, keyboard navigation
+6. **Edge Cases** - Null values, empty strings, boundary conditions
+7. **Component Integration** - Complex prop combinations
+
+### Coverage Targets
+- **100% line coverage** for all components in authentication and security-critical modules (login, password reset, registration)
+- **Minimum 90% line coverage** for all other components
+- **100% coverage** for critical business logic, composables, and services
+- **All public props and events** must be tested
+- **All conditional rendering** must be tested
+
+---
+
+## Performance and Best Practices
+
+### Test Performance
+- Use `beforeEach` for common setup
+- Avoid unnecessary DOM queries
+- Use `async/await` for prop changes
+- Use `nextTick()` for DOM updates after reactive changes
+
+### Critical: Always use await nextTick() after setProps
+When testing Vue components, **always use `await nextTick()` after `setProps()`** when checking DOM changes or styles:
+
+```typescript
+import { nextTick } from 'vue';
+
+// CORRECT: Use await nextTick() after setProps
+it('should update DOM when prop changes', async () => {
+    await wrapper.setProps({ disabled: true });
+    await nextTick(); // Wait for Vue to update DOM
+    expect(wrapper.attributes('disabled')).toBeDefined();
+});
+
+it('should apply correct styles after prop change', async () => {
+    await wrapper.setProps({ items: newItems });
+    await nextTick(); // Wait for computed properties and DOM updates
+    const items = wrapper.findAll('.grid-item');
+    expect(items).toHaveLength(2);
+});
+
+// WRONG: Missing await nextTick() - test may fail intermittently
+it('should update DOM when prop changes', async () => {
+    await wrapper.setProps({ disabled: true });
+    // Missing nextTick() - DOM may not be updated yet!
+    expect(wrapper.attributes('disabled')).toBeDefined();
+});
+```
+
+**Why is this important?**
+- `await wrapper.setProps()` triggers Vue's reactivity system
+- Computed properties, watchers, and DOM updates happen in the **next tick**
+- Without `await nextTick()`, tests check DOM before Vue finishes rendering
+- This causes intermittent test failures that are hard to debug
+
+### Best Practices
+```typescript
+// Good: Use async/await for prop changes
+it('should update when prop changes', async () => {
+    await wrapper.setProps({ disabled: true });
+    expect(wrapper.attributes('disabled')).toBeDefined();
+});
+
+// Good: Use nextTick for DOM updates
+it('should update DOM after value change', async () => {
+    await wrapper.setProps({ modelValue: 'new value' });
+    await nextTick();
+    expect(wrapper.find('input').element.value).toBe('new value');
+});
+
+// Bad: Don't forget await
+it('should update when prop changes', () => {
+    wrapper.setProps({ disabled: true }); // Missing await
+    expect(wrapper.attributes('disabled')).toBeDefined();
+});
+```
+
+### Test Isolation
+- Each test should be independent
+- Use `beforeEach` for setup, not shared state
+- Clean up after tests if needed
+- Don't rely on test execution order
+
+---
+
+## Mocking and Stubbing
+
+### Component Mocking
+Mock external components and dependencies:
+```typescript
+// Mock external components
+vi.mock('{{COMPONENT_LIB_IMPORT}}', () => ({
+    Button: {
+        name: 'Button',
+        template: '<button class="button-mock"><slot /></button>',
+        props: ['variant', 'icon', 'dataTestId'],
+        emits: ['click'],
+    },
+}));
+
+// Mock third-party libraries
+vi.mock('ag-grid-vue3', () => ({
+    AgGridVue: {
+        name: 'AgGridVue',
+        template: '<div class="ag-grid-mock"></div>',
+        props: ['rowData', 'columnDefs'],
+    },
+}));
+```
+
+### Global Mocks
+Set up global mocks in test setup:
+```typescript
+// Mock window.matchMedia
+Object.defineProperty(window, 'matchMedia', {
+    writable: true,
+    value: vi.fn().mockImplementation((query: string) => ({
+        matches: false,
+        media: query,
+        onchange: null,
+        addListener: vi.fn(),
+        removeListener: vi.fn(),
+    })),
+});
+
+// Mock ResizeObserver
+global.ResizeObserver = vi.fn().mockImplementation(() => ({
+    observe: vi.fn(),
+    unobserve: vi.fn(),
+    disconnect: vi.fn(),
+}));
+```
+
+### API and Service Mocking
+```typescript
+// Mock API calls
+vi.mock('{{MODULE_PATH}}/services/api', () => ({
+    fetchData: vi.fn().mockResolvedValue({ data: [] }),
+    postData: vi.fn().mockResolvedValue({ success: true }),
+}));
+
+// Mock composables
+vi.mock('@/composables/useApi', () => ({
+    useApi: () => ({
+        loading: ref(false),
+        error: ref(null),
+        data: ref([]),
+        fetch: vi.fn(),
+    }),
+}));
+```
+
+---
+
+## Accessibility Testing
+
+### Required Accessibility Tests
+Every component must test **actual** accessibility features (not just data-testid):
+
+```typescript
+describe('Accessibility', () => {
+    it('should have required attribute when required is true', async () => {
+        await wrapper.setProps({ required: true });
+        const input = wrapper.find('input');
+        expect(input.attributes('required')).toBeDefined();
+    });
+
+    it('should have disabled attribute when disabled is true', async () => {
+        await wrapper.setProps({ disabled: true });
+        const input = wrapper.find('input');
+        expect(input.attributes('disabled')).toBeDefined();
+    });
+
+    it('should have aria-hidden on decorative icons', async () => {
+        await wrapper.setProps({ icon: 'search' });
+        const icon = wrapper.find('.icon');
+        expect(icon.attributes('aria-hidden')).toBe('true');
+    });
+
+    it('should have proper aria-label for screen readers', () => {
+        const button = wrapper.find('button');
+        expect(button.attributes('aria-label')).toBe('Submit form');
+    });
+});
+```
+
+### Important: Accessibility vs Component Integration
+**Do not confuse accessibility tests with component integration tests:**
+
+```typescript
+// BAD: This is NOT an accessibility test
+describe('Accessibility', () => {
+    it('should have data-testid', () => {
+        expect(wrapper.attributes('data-testid')).toBe('test-component');
+    });
+
+    it('should pass props to child components', () => {
+        const child = wrapper.findComponent(ChildComponent);
+        expect(child.props('data')).toBeDefined();
+    });
+});
+
+// GOOD: Rename to Component Integration
+describe('Component Integration', () => {
+    it('should have proper data-testid for testing', () => {
+        expect(wrapper.attributes('data-testid')).toBe('test-component');
+    });
+
+    it('should pass item data to child components', () => {
+        const child = wrapper.findComponent(ChildComponent);
+        expect(child.props('item')).toEqual(mockData);
+    });
+});
+```
+
+### ARIA Testing
+- Test `aria-hidden` on decorative elements
+- Test `aria-label` and `aria-describedby`
+- Test `role` attributes where applicable
+- Test keyboard navigation support (Tab, Enter, Escape)
+- Test focus management
+
+---
+
+## State and Event Testing
+
+### v-model Testing
+Test two-way data binding:
+```typescript
+describe('v-model Functionality', () => {
+    it('should update modelValue when input value changes', async () => {
+        const input = wrapper.find('input');
+        await input.setValue('test value');
+        expect(wrapper.vm.modelValue).toBe('test value');
+    });
+
+    it('should update input value when modelValue changes', async () => {
+        await wrapper.setProps({ modelValue: 'new value' });
+        const input = wrapper.find('input');
+        expect(input.element.value).toBe('new value');
+    });
+
+    it('should handle null modelValue', async () => {
+        await wrapper.setProps({ modelValue: null });
+        const input = wrapper.find('input');
+        expect(input.element.value).toBe('');
+    });
+});
+```
+
+### Event Emission Testing
+```typescript
+describe('Event Handling', () => {
+    it('should emit update:modelValue with correct value', async () => {
+        const input = wrapper.find('input');
+        await input.setValue('test');
+        await input.trigger('input');
+
+        expect(wrapper.emitted('update:modelValue')).toBeTruthy();
+        expect(wrapper.emitted('update:modelValue')?.[0]).toEqual(['test']);
+    });
+
+    it('should emit multiple events in sequence', async () => {
+        await wrapper.trigger('click');
+        await wrapper.trigger('focus');
+
+        expect(wrapper.emitted('click')).toHaveLength(1);
+        expect(wrapper.emitted('focus')).toHaveLength(1);
+    });
+});
+```
+
+---
+
+## Test Documentation
+
+### Test Comments
+- Add comments for complex test logic
+- Explain why certain assertions are needed
+- Document edge cases and their reasoning
+
+### Test Organization
+```typescript
+describe('ComponentName Component', () => {
+    // Basic functionality tests
+    describe('Basic Rendering', () => {
+        // Tests for fundamental component structure
+    });
+
+    // Props and configuration tests
+    describe('Props Testing', () => {
+        // Tests for all component props
+    });
+
+    // State-based behavior tests
+    describe('States', () => {
+        // Tests for different component states
+    });
+
+    // User interaction tests
+    describe('Event Handling', () => {
+        // Tests for user interactions and events
+    });
+
+    // Accessibility compliance tests
+    describe('Accessibility', () => {
+        // Tests for accessibility features
+    });
+
+    // Error handling and edge cases
+    describe('Edge Cases', () => {
+        // Tests for boundary conditions and error states
+    });
+
+    // Complex integration scenarios
+    describe('Component Integration', () => {
+        // Tests for complex prop combinations and interactions
+    });
+});
+```
+
+### Test Documentation Requirements
+- Each test file should have a clear purpose
+- Complex test logic should be documented
+- Edge cases should be explained
+- Integration tests should describe the scenario
+
+---
+
+## Testing Checklist
+
+### Before Writing Tests
+- [ ] Understand component requirements and props
+- [ ] Identify all public API (props, events, slots)
+- [ ] Plan test structure and organization
+- [ ] Identify dependencies to mock
+
+### During Test Writing
+- [ ] Test all props with valid and invalid values
+- [ ] Test all component states (disabled, error, loading)
+- [ ] Test all event emissions
+- [ ] Test accessibility features
+- [ ] Test edge cases and error conditions
+- [ ] Use descriptive test names
+- [ ] Follow async/await patterns
+
+### After Writing Tests
+- [ ] Run tests to ensure they pass
+- [ ] Check test coverage meets requirements
+- [ ] Verify tests are independent and isolated
+- [ ] Review test names for clarity
+- [ ] Ensure all edge cases are covered
+
+### Quality Gates
+- [ ] All tests pass consistently
+- [ ] Test coverage >= 80%
+- [ ] No flaky or intermittent tests
+- [ ] Tests run in reasonable time
+- [ ] Tests are maintainable and readable
+
+---
+
+## Common Testing Anti-Patterns
+
+### Don't Do This
+```typescript
+// Don't test implementation details
+it('should call handleClick method', () => {
+    const spy = vi.spyOn(wrapper.vm, 'handleClick');
+    wrapper.trigger('click');
+    expect(spy).toHaveBeenCalled();
+});
+
+// Don't use magic numbers without context
+it('should have correct width', () => {
+    expect(wrapper.element.style.width).toBe('100px');
+});
+
+// Don't test multiple things in one test
+it('should render and handle click and emit event', () => {
+    expect(wrapper.exists()).toBe(true);
+    wrapper.trigger('click');
+    expect(wrapper.emitted('click')).toBeTruthy();
+});
+```
+
+### Do This Instead
+```typescript
+// Test behavior, not implementation
+it('should emit click event when clicked', async () => {
+    await wrapper.trigger('click');
+    expect(wrapper.emitted('click')).toBeTruthy();
+});
+
+// Use descriptive assertions
+it('should have full width when wide prop is true', async () => {
+    await wrapper.setProps({ wide: true });
+    expect(wrapper.classes()).toContain('is-wide');
+});
+
+// Test one thing per test
+it('should render button element', () => {
+    expect(wrapper.element.tagName).toBe('BUTTON');
+});
+
+it('should emit click event when clicked', async () => {
+    await wrapper.trigger('click');
+    expect(wrapper.emitted('click')).toBeTruthy();
+});
+```
+
+---
+
+## Additional Resources
+
+### VITEST Documentation
+- [VITEST Testing Framework](https://vitest.dev/)
+- [Vue Test Utils](https://test-utils.vuejs.org/)
+- [Testing Vue Components](https://vuejs.org/guide/scaling-up/testing.html)
+
+### Project-Specific Testing
+- Use existing test files as examples
+- Follow established patterns in the codebase
+- Maintain consistency with existing test structure
+- Use project-specific mocks and utilities
+
+### Testing Tools
+- VITEST for test runner and assertions
+- Vue Test Utils for component testing
+- jsdom for DOM simulation
+- Mock Service Worker for API mocking (if needed)
+
+---
+
+## Essential Test Commands
+
+### Development Commands
+```bash
+npm run test              # Run tests in watch mode
+npm run test:run         # Run tests once
+npm run test:coverage    # Generate coverage report
+npm run test:ui          # Open Vitest UI
+```
+
+### CI/CD Commands
+```bash
+npm run test:ci          # Run tests in CI mode
+npm run test:coverage:ci # Generate coverage for CI
+```
+
+### Debugging Tests
+```bash
+npm run test -- --reporter=verbose     # Verbose output
+npm run test -- --run --reporter=json  # JSON output for parsing
+```

package/templates/packs/vitest/pack.json

@@ -0,0 +1,6 @@
+{
+  "name": "Vitest",
+  "description": "Unit testy z Vitest + Vue Test Utils",
+  "default": true,
+  "placeholders": {}
+}