code-ai-installer 1.5.6 → 2.1.0

package/.agents/skills/testing-strategy-js/SKILL.md

@@ -0,0 +1,636 @@
+---
+name: testing-strategy-js
+description: Стратегия тестирования для JS/TS проектов — unit (Vitest), integration (API/DB), e2e (Playwright). AAA-паттерн, Vitest конфиг, React Testing Library, моки внешних сервисов, coverage thresholds, naming conventions, CI pipeline. Активируй при написании новых тестов, рефакторинге существующих, или при вопросах «как правильно тестировать X».
+---
+
+# Skill: Testing Strategy (JS/TS)
+
+Конкретные паттерны, шаблоны и DO/DON'T для написания надёжных тестов.
+
+**Разделы:**
+1. [Пирамида тестов и границы](#1-пирамида-тестов)
+2. [Unit-тесты](#2-unit-тесты)
+3. [React-компоненты (RTL)](#3-react-компоненты-rtl)
+4. [Integration-тесты](#4-integration-тесты)
+5. [Моки и Test Doubles](#5-моки-и-test-doubles)
+6. [Naming и структура](#6-naming-и-структура)
+7. [Coverage и CI](#7-coverage-и-ci)
+8. [Anti-patterns](#8-anti-patterns)
+
+---
+
+## 1. Пирамида тестов
+
+```
+         ┌─────────┐
+         │  E2E    │  ~5%  Playwright — критичные потоки
+         ├─────────┤
+         │ Integr. │  ~15% API routes, DB, контракты
+         ├─────────┤
+         │  Unit   │  ~80% Функции, хуки, компоненты, утилиты
+         └─────────┘
+```
+
+| Уровень | Что тестировать | Инструмент | Скорость |
+|---------|----------------|-----------|---------|
+| **Unit** | Чистые функции, утилиты, хуки, React-компоненты | Vitest + RTL | < 5ms/тест |
+| **Integration** | API routes, DB-запросы, контракты между модулями | Vitest + supertest | < 500ms/тест |
+| **E2E** | Логин, ключевые CRUD, оплата, критичные потоки | Playwright | < 30s/тест |
+
+> [!IMPORTANT]
+> E2E → только для критичных потоков. Всё остальное ловить на unit/integration.
+> Подробнее по E2E → `$qa-e2e-playwright`.
+
+---
+
+## 2. Unit-тесты
+
+### ✅ DO: AAA-паттерн (Arrange → Act → Assert)
+
+```js
+import { describe, it, expect } from 'vitest';
+import { calculateDiscount } from './pricing.js';
+
+describe('calculateDiscount', () => {
+  it('should apply percentage discount to base price', () => {
+    // Arrange
+    const basePrice = 100;
+    const discountPercent = 20;
+
+    // Act
+    const result = calculateDiscount(basePrice, discountPercent);
+
+    // Assert
+    expect(result).toBe(80);
+  });
+
+  it('should clamp discount at 0 (never negative price)', () => {
+    const result = calculateDiscount(50, 120);
+    expect(result).toBe(0);
+  });
+
+  it('should return original price when discount is 0', () => {
+    expect(calculateDiscount(100, 0)).toBe(100);
+  });
+
+  it('should throw on negative base price', () => {
+    expect(() => calculateDiscount(-10, 5)).toThrow('Price must be non-negative');
+  });
+});
+```
+
+### ✅ DO: тестировать edge cases явно
+
+```js
+describe('parseTimerValue', () => {
+  // Happy path
+  it('should parse "05:30" into { minutes: 5, seconds: 30 }', () => {
+    expect(parseTimerValue('05:30')).toEqual({ minutes: 5, seconds: 30 });
+  });
+
+  // Boundaries
+  it('should handle "00:00" as zero timer', () => {
+    expect(parseTimerValue('00:00')).toEqual({ minutes: 0, seconds: 0 });
+  });
+
+  it('should handle "99:59" as max timer', () => {
+    expect(parseTimerValue('99:59')).toEqual({ minutes: 99, seconds: 59 });
+  });
+
+  // Error paths
+  it('should throw on invalid format "abc"', () => {
+    expect(() => parseTimerValue('abc')).toThrow();
+  });
+
+  it('should throw on seconds > 59', () => {
+    expect(() => parseTimerValue('01:60')).toThrow();
+  });
+
+  // Null / undefined
+  it('should throw on null input', () => {
+    expect(() => parseTimerValue(null)).toThrow();
+  });
+});
+```
+
+### ✅ DO: тестировать custom hooks через renderHook
+
+```js
+import { renderHook, act } from '@testing-library/react';
+import { useCounter } from './useCounter.js';
+
+describe('useCounter', () => {
+  it('should initialize with default value 0', () => {
+    const { result } = renderHook(() => useCounter());
+    expect(result.current.count).toBe(0);
+  });
+
+  it('should initialize with custom value', () => {
+    const { result } = renderHook(() => useCounter(10));
+    expect(result.current.count).toBe(10);
+  });
+
+  it('should increment count', () => {
+    const { result } = renderHook(() => useCounter());
+    act(() => result.current.increment());
+    expect(result.current.count).toBe(1);
+  });
+
+  it('should not go below 0', () => {
+    const { result } = renderHook(() => useCounter(0));
+    act(() => result.current.decrement());
+    expect(result.current.count).toBe(0);
+  });
+});
+```
+
+---
+
+## 3. React-компоненты (RTL)
+
+### ✅ DO: тестировать поведение, а не реализацию
+
+```js
+import { render, screen, fireEvent } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { SearchInput } from './SearchInput.jsx';
+
+describe('SearchInput', () => {
+  it('should call onSearch with query when button clicked', async () => {
+    const user = userEvent.setup();
+    const onSearch = vi.fn();
+
+    render(<SearchInput onSearch={onSearch} />);
+
+    await user.type(screen.getByRole('textbox', { name: /search/i }), 'laptop');
+    await user.click(screen.getByRole('button', { name: /search/i }));
+
+    expect(onSearch).toHaveBeenCalledWith('laptop');
+    expect(onSearch).toHaveBeenCalledTimes(1);
+  });
+
+  it('should show error message for empty query', async () => {
+    const user = userEvent.setup();
+    render(<SearchInput onSearch={vi.fn()} />);
+
+    await user.click(screen.getByRole('button', { name: /search/i }));
+
+    expect(screen.getByRole('alert')).toHaveTextContent(/enter a query/i);
+  });
+
+  it('should disable button while loading', () => {
+    render(<SearchInput onSearch={vi.fn()} isLoading />);
+
+    expect(screen.getByRole('button', { name: /search/i })).toBeDisabled();
+  });
+});
+```
+
+### ❌ DON'T: тестировать детали реализации
+
+```js
+// ❌ Плохо: зависимость от внутреннего state
+it('should set state to true', () => {
+  const { result } = renderHook(() => useToggle());
+  act(() => result.current[1]());
+  // Проверяем internal state — хрупко
+  expect(result.current[0]).toBe(true);
+});
+
+// ✅ Хорошо: проверяем поведение через DOM
+it('should show content after toggle click', async () => {
+  const user = userEvent.setup();
+  render(<Accordion title="Details">Content</Accordion>);
+
+  expect(screen.queryByText('Content')).not.toBeInTheDocument();
+  await user.click(screen.getByRole('button', { name: /details/i }));
+  expect(screen.getByText('Content')).toBeVisible();
+});
+```
+
+### ✅ DO: RTL queries по приоритету
+
+```js
+// Приоритет запросов (от лучшего к худшему):
+// 1. getByRole     — семантические роли (лучше всего)
+// 2. getByLabelText — формы
+// 3. getByText     — статический текст
+// 4. getByTestId   — последний resort
+
+// ✅ По роли — устойчиво к изменению вёрстки
+screen.getByRole('button', { name: /save/i });
+screen.getByRole('textbox', { name: /email/i });
+screen.getByRole('heading', { level: 2 });
+
+// ✅ По label — формы
+screen.getByLabelText(/password/i);
+
+// ⚠️ По тексту — менее устойчиво к i18n
+screen.getByText(/no templates found/i);
+
+// 🔧 По testid — когда нет семантики
+screen.getByTestId('popup-container');
+```
+
+---
+
+## 4. Integration-тесты
+
+### ✅ DO: API handler тесты с supertest
+
+```js
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import request from 'supertest';
+import { createApp } from '../app.js';
+
+describe('POST /api/products', () => {
+  let app;
+
+  beforeAll(() => {
+    app = createApp({ db: testDb });
+  });
+
+  afterAll(async () => {
+    await testDb.cleanup();
+  });
+
+  it('should create product and return 201', async () => {
+    const res = await request(app)
+      .post('/api/products')
+      .send({ name: 'Summer Hat', price: 25, category: 'accessories' })
+      .expect(201);
+
+    expect(res.body).toMatchObject({
+      name: 'Summer Hat',
+      price: 25,
+      category: 'accessories',
+    });
+    expect(res.body).toHaveProperty('id');
+    expect(res.body).toHaveProperty('createdAt');
+  });
+
+  it('should reject duplicate product name with 409', async () => {
+    await request(app)
+      .post('/api/products')
+      .send({ name: 'Unique Widget', price: 10, category: 'tools' });
+
+    await request(app)
+      .post('/api/products')
+      .send({ name: 'Unique Widget', price: 20, category: 'tools' })
+      .expect(409);
+  });
+
+  it('should reject invalid price with 400 and error details', async () => {
+    const res = await request(app)
+      .post('/api/products')
+      .send({ name: 'Bad Item', price: -5, category: 'tools' })
+      .expect(400);
+
+    expect(res.body.error).toMatch(/price/i);
+  });
+});
+```
+
+### ✅ DO: тесты контрактов (проверяем форму ответа, не бизнес-логику)
+
+```js
+describe('GET /api/templates', () => {
+  it('should match API contract shape', async () => {
+    const res = await request(app)
+      .get('/api/templates')
+      .expect(200);
+
+    expect(res.body).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          id: expect.any(String),
+          name: expect.any(String),
+          category: expect.any(String),
+          thumbnail: expect.stringMatching(/^https?:\/\//),
+        }),
+      ])
+    );
+  });
+});
+```
+
+---
+
+## 5. Моки и Test Doubles
+
+### ✅ DO: мокать внешние границы, не внутреннюю логику
+
+```js
+// ✅ Мокаем внешний HTTP API
+vi.mock('../services/openai.js', () => ({
+  generateText: vi.fn().mockResolvedValue('Mocked AI response'),
+}));
+
+// ✅ Мокаем таймеры
+import { vi, beforeEach, afterEach } from 'vitest';
+
+beforeEach(() => vi.useFakeTimers());
+afterEach(() => vi.useRealTimers());
+
+it('should expire item after timeout', () => {
+  const onExpire = vi.fn();
+  startTimer(onExpire, 5000);
+
+  vi.advanceTimersByTime(5000);
+
+  expect(onExpire).toHaveBeenCalledOnce();
+});
+```
+
+### ✅ DO: фабрики тестовых данных вместо хардкода
+
+```js
+// test-utils/factories.js
+
+/**
+ * Создаёт тестовый объект продукта с возможностью override.
+ * @param {Partial<Product>} overrides - поля для переопределения.
+ * @returns {Product} тестовый продукт.
+ */
+function createProduct(overrides = {}) {
+  return {
+    id: crypto.randomUUID(),
+    name: 'Test Product',
+    price: 29.99,
+    category: 'widgets',
+    active: true,
+    createdAt: new Date().toISOString(),
+    ...overrides,
+  };
+}
+
+// Использование в тестах:
+it('should deactivate expired product', () => {
+  const product = createProduct({ active: true, expiresAt: '2024-01-01' });
+  const result = deactivateExpired(product);
+  expect(result.active).toBe(false);
+});
+```
+
+### ❌ DON'T: чрезмерные моки
+
+```js
+// ❌ Замокали всё — тест ничего не проверяет
+vi.mock('../db.js');
+vi.mock('../validator.js');
+vi.mock('../logger.js');
+vi.mock('../event-bus.js');
+
+it('should save product', async () => {
+  db.save.mockResolvedValue({ id: 1 });
+  validator.validate.mockReturnValue(true);
+
+  await saveProduct({ name: 'Widget' });
+
+  expect(db.save).toHaveBeenCalled(); // мы проверяем моки, не логику
+});
+
+// ✅ Интеграционный тест проверяет реальный flow
+it('should save valid product to DB', async () => {
+  const result = await saveProduct({ name: 'Premium Widget', price: 29.99, category: 'digital' });
+  expect(result.id).toBeDefined();
+
+  const stored = await db.findById(result.id);
+  expect(stored.name).toBe('Premium Widget');
+});
+```
+
+### Что мокать, а что нет
+
+| Мокать ✅ | НЕ мокать ❌ |
+|----------|-------------|
+| HTTP API (fetch, axios) | Собственные утилиты |
+| Внешние сервисы (OpenAI, Stripe, Redis) | Простые трансформации данных |
+| Таймеры (setTimeout, setInterval) | Router / навигация (если не E2E) |
+| File system (fs) | Внутренние модули (теряется смысл integration) |
+| crypto.randomUUID (детерминизм) | — |
+
+---
+
+## 6. Naming и структура
+
+### Организация файлов
+
+```
+src/
+├── utils/
+│   ├── pricing.js
+│   └── pricing.test.js          # Unit — рядом с кодом
+├── hooks/
+│   ├── useTimer.js
+│   └── useTimer.test.js         # Unit — рядом с кодом
+├── components/
+│   ├── SearchInput.jsx
+│   └── SearchInput.test.jsx     # RTL — рядом с компонентом
+├── api/
+│   ├── products.handler.js
+│   └── products.integration.test.js  # Integration — рядом с маршрутом
+└── e2e/                          # E2E — отдельная папка
+    └── specs/
+```
+
+### ✅ DO: describe/it naming convention
+
+```js
+// Формат: describe('[Unit/Module]') → it('should [ACTION] when [CONDITION]')
+describe('InputValidator', () => {
+  describe('validate', () => {
+    it('should return valid for correct input value', () => { /* ... */ });
+    it('should return invalid when value is empty', () => { /* ... */ });
+    it('should return invalid when value exceeds max length', () => { /* ... */ });
+  });
+
+  describe('isExpired', () => {
+    it('should return true when expiresAt is in the past', () => { /* ... */ });
+    it('should return false when expiresAt is in the future', () => { /* ... */ });
+    it('should return false when expiresAt is null (never expires)', () => { /* ... */ });
+  });
+});
+```
+
+### Чеклист для каждого тестируемого модуля
+
+- [ ] Happy path (основной сценарий)
+- [ ] Edge cases (0, null, undefined, пустая строка, пустой массив)
+- [ ] Boundaries (min/max значения)
+- [ ] Error paths (невалидный ввод, сетевые ошибки)
+- [ ] Async (таймауты, race conditions — если применимо)
+
+---
+
+## 7. Coverage и CI
+
+### Vitest конфиг
+
+```js
+// vitest.config.js
+import { defineConfig } from 'vitest/config';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    setupFiles: ['./src/test-setup.js'],
+    include: ['src/**/*.test.{js,jsx,ts,tsx}'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'html', 'lcov'],
+      include: ['src/**/*.{js,jsx,ts,tsx}'],
+      exclude: [
+        'src/**/*.test.*',
+        'src/**/*.spec.*',
+        'src/**/index.{js,ts}',     // barrel files
+        'src/test-utils/**',
+        'src/**/*.d.ts',
+      ],
+      thresholds: {
+        statements: 80,
+        branches: 75,
+        functions: 80,
+        lines: 80,
+      },
+    },
+  },
+});
+```
+
+### Setup файл
+
+```js
+// src/test-setup.js
+import '@testing-library/jest-dom/vitest';
+
+// Глобальный cleanup (RTL >= v14 делает это автоматически)
+// import { cleanup } from '@testing-library/react';
+// afterEach(cleanup);
+```
+
+### Coverage thresholds
+
+| Метрика | Минимум | Комфорт | Отлично |
+|---------|---------|---------|---------|
+| Statements | 70% | 80% | 90%+ |
+| Branches | 65% | 75% | 85%+ |
+| Functions | 70% | 80% | 90%+ |
+| Lines | 70% | 80% | 90%+ |
+
+### Scripts в package.json
+
+```json
+{
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:ui": "vitest --ui"
+  }
+}
+```
+
+---
+
+## 8. Anti-patterns
+
+### ❌ DON'T: тесты зависят от порядка выполнения
+
+```js
+// ❌ Плохо: второй тест зависит от первого
+let sharedState;
+
+it('should create item', () => {
+  sharedState = createItem({ name: 'test' });
+  expect(sharedState.id).toBeDefined();
+});
+
+it('should update item', () => {
+  updateItem(sharedState.id, { name: 'updated' }); // sharedState из предыдущего теста
+});
+
+// ✅ Хорошо: каждый тест создаёт свои данные
+it('should update item', () => {
+  const item = createItem({ name: 'test' });
+  const updated = updateItem(item.id, { name: 'updated' });
+  expect(updated.name).toBe('updated');
+});
+```
+
+### ❌ DON'T: snapshot-тесты без осмысления
+
+```js
+// ❌ Бессмысленный snapshot — любое изменение ломает тест
+it('renders correctly', () => {
+  const { container } = render(<ComplexForm />);
+  expect(container).toMatchSnapshot(); // 500 строк snapshot, никто не ревьюит
+});
+
+// ✅ Snapshot только для стабильного output
+it('should render error boundary fallback', () => {
+  const { container } = render(<ErrorFallback error={new Error('Oops')} />);
+  expect(container).toMatchInlineSnapshot(`
+    <div class="error-fallback">
+      <p>Something went wrong: Oops</p>
+    </div>
+  `);
+});
+```
+
+### ❌ DON'T: «магические» значения без пояснений
+
+```js
+// ❌ Что за 42? Почему 3?
+expect(result).toBe(42);
+expect(items).toHaveLength(3);
+
+// ✅ Значения понятны из контекста
+const BASE_PRICE = 100;
+const DISCOUNT = 58;  // 58% discount
+const EXPECTED_PRICE = 42; // 100 - 58
+
+expect(calculatePrice(BASE_PRICE, DISCOUNT)).toBe(EXPECTED_PRICE);
+```
+
+### ❌ DON'T: async без await
+
+```js
+// ❌ Тест проходит всегда — assertion не выполняется
+it('should fetch data', () => {
+  fetchData().then(data => {
+    expect(data).toBeDefined(); // никогда не выполнится как assertion
+  });
+});
+
+// ✅ Правильно: await + async
+it('should fetch data', async () => {
+  const data = await fetchData();
+  expect(data).toBeDefined();
+});
+```
+
+---
+
+## Definition of Done (тесты для модуля)
+
+- [ ] Happy path покрыт
+- [ ] ≥ 2 edge case / boundary
+- [ ] ≥ 1 error path
+- [ ] Названия `should [verb] when [condition]`
+- [ ] Нет зависимости между тестами
+- [ ] Фабрики для тестовых данных (если повторяются)
+- [ ] Coverage ≥ 80% statements
+- [ ] Нет `any`, нет `// @ts-ignore` в тестах
+
+---
+
+## См. также
+- `$tests-quality-review` — ревью качества тестов
+- `$qa-e2e-playwright` — E2E через Playwright
+- `$qa-browser-testing` — визуальное тестирование в Antigravity
+- `$es2025-beast-practices` — современный JS для написания чистого кода
+- `$dev-reference-snippets` — TDD, React, API примеры

package/.agents/skills/testing-strategy-js/agents/claude.json

@@ -0,0 +1,19 @@
+{
+  "name": "testing-strategy-js",
+  "display_name": "Стратегия тестирования JS/TS",
+  "description": "Стратегия тестирования для JS/TS проектов — unit (Vitest), integration (API/DB), e2e (Playwright). AAA-паттерн, Vitest конфиг, React Testing Library, моки внешних сервисов, coverage thresholds, naming conventions, CI pipeline. Активируй при написании новых тестов, рефакторинге существующих, или при вопросах «как правильно тестировать X».",
+  "default_prompt": "Используй $testing-strategy-js, когда задача относится к навыку \"Стратегия тестирования JS/TS\".",
+  "triggers": [
+    "testing-strategy-js",
+    "testing strategy js",
+    "Стратегия тестирования JS/TS",
+    "Стратегия тестирования для JS/TS проектов — unit (Vitest), integration (API/DB), e2e (Playwright)"
+  ],
+  "capabilities": [
+    "testing",
+    "strategy",
+    "js"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/.agents/skills/testing-strategy-js/agents/copilot.json

@@ -0,0 +1,19 @@
+{
+  "name": "testing-strategy-js",
+  "display_name": "Стратегия тестирования JS/TS",
+  "description": "Стратегия тестирования для JS/TS проектов — unit (Vitest), integration (API/DB), e2e (Playwright). AAA-паттерн, Vitest конфиг, React Testing Library, моки внешних сервисов, coverage thresholds, naming conventions, CI pipeline. Активируй при написании новых тестов, рефакторинге существующих, или при вопросах «как правильно тестировать X».",
+  "default_prompt": "Используй $testing-strategy-js, когда задача относится к навыку \"Стратегия тестирования JS/TS\".",
+  "triggers": [
+    "testing-strategy-js",
+    "testing strategy js",
+    "Стратегия тестирования JS/TS",
+    "Стратегия тестирования для JS/TS проектов — unit (Vitest), integration (API/DB), e2e (Playwright)"
+  ],
+  "capabilities": [
+    "testing",
+    "strategy",
+    "js"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/.agents/skills/testing-strategy-js/agents/gemini.json

@@ -0,0 +1,19 @@
+{
+  "name": "testing-strategy-js",
+  "display_name": "Стратегия тестирования JS/TS",
+  "description": "Стратегия тестирования для JS/TS проектов — unit (Vitest), integration (API/DB), e2e (Playwright). AAA-паттерн, Vitest конфиг, React Testing Library, моки внешних сервисов, coverage thresholds, naming conventions, CI pipeline. Активируй при написании новых тестов, рефакторинге существующих, или при вопросах «как правильно тестировать X».",
+  "default_prompt": "Используй $testing-strategy-js, когда задача относится к навыку \"Стратегия тестирования JS/TS\".",
+  "triggers": [
+    "testing-strategy-js",
+    "testing strategy js",
+    "Стратегия тестирования JS/TS",
+    "Стратегия тестирования для JS/TS проектов — unit (Vitest), integration (API/DB), e2e (Playwright)"
+  ],
+  "capabilities": [
+    "testing",
+    "strategy",
+    "js"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}