code-ai-installer 1.1.11 → 1.3.0

package/.agents/qa_browser_testing/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: qa_browser_testing
+description: Визуальное E2E-тестирование через встроенный Antigravity Browser — Pre-Auth Handoff, browser_subagent, скриншоты, visual parity, evidence-сбор.
+last_verified: 2026-03-11
+version: 1.0
+---
+
+# Skill: Antigravity Browser Testing
+
+## Назначение
+
+Тестирование через **встроенный браузер Google Antigravity** (`browser_subagent`).
+Основной инструмент Tester-агента для визуальной проверки, UI parity и DEMO gate.
+
+> [!IMPORTANT]
+> Этот скил — для **ручного-автоматизированного** тестирования внутри Antigravity.
+> Для CI/CD автоматизации (spec-файлы, pipeline) → `$qa_e2e_playwright`.
+
+---
+
+## Когда использовать
+
+- Тестирование Wix Dashboard / Shopify Admin (закрытая среда)
+- Visual parity: сравнение реализации с дизайн-источником (Stitch / Figma / HTML-ref)
+- DEMO gate: проверка DEV-xx срезов
+- Быстрая regression проверка UI
+- Сбор evidence (скриншоты + видео) для QA Report
+
+## Когда НЕ использовать
+
+- Нужна автоматизация в CI/CD pipeline → `$qa_e2e_playwright`
+- Unit/integration тестирование → Vitest
+- API contract testing → `$qa_api_contract_tests`
+- Вычислительная логика → unit-тесты
+
+---
+
+## Инструменты
+
+| Инструмент | Что делает | Когда |
+|-----------|-----------|-------|
+| `browser_subagent` | Открывает страницу, кликает, вводит текст, проверяет UI | Основной |
+| `capture_browser_screenshot` | Делает скриншот текущей страницы | Каждый шаг проверки |
+| `open_browser_url` | Переходит на URL | Навигация |
+| `read_browser_page` | Читает DOM/текст страницы | Проверка контента |
+| `click_browser_element` | Кликает по элементу | Интерактивная проверка |
+
+> [!NOTE]
+> Каждый вызов `browser_subagent` автоматически записывает `.webp` видео.
+> Видео = evidence для QA report и walkthrough.
+
+---
+
+## Pre-Auth Handoff (Wix / Shopify)
+
+> **Триггер:** пользователь указывает **«Wix»** или **«Shopify»** при переходе к TEST gate.
+
+### Протокол
+
+**Шаг 1 — Запросить авторизацию:**
+```
+🌐 Pre-Auth Handoff: обнаружен триггер [Wix/Shopify].
+Пожалуйста:
+1. Откройте браузер Antigravity
+2. Залогиньтесь в [Wix Dashboard / Shopify Admin]
+3. Перейдите на страницу, которую нужно протестировать
+4. Напишите: "Браузер готов"
+```
+
+**Шаг 2 — Пользователь авторизуется и открывает нужную страницу.**
+
+**Шаг 3 — Tester запускает `browser_subagent` со строгими правилами:**
+- ❌ НЕ открывать новые URL (только работать с текущей страницей)
+- ❌ НЕ пытаться навигировать на localhost
+- ✅ Делать скриншот на КАЖДОМ шаге проверки
+- ✅ Кликать, переключать, проверять UI
+- ✅ Записать видео (`.webp`) для evidence
+
+**Шаг 4 — Анализ скриншотов и формирование findings.**
+
+### Ограничения
+
+| Работает ✅ | Не работает ❌ |
+|------------|---------------|
+| `manage.wix.com` | `localhost` |
+| `admin.shopify.com` | Self-signed SSL |
+| Любой URL с валидным SSL | Wix sandbox iFrame API |
+| Auth state сохраняется | Session expires (~24h) |
+
+---
+
+## Visual Parity через Antigravity Browser
+
+> [!IMPORTANT]
+> **Source of truth определяется UX Designer** (обязательный вопрос #2 Clarification Protocol).
+> Если не указан — запросить перед проверкой.
+
+### Алгоритм
+
+```
+1. Получить reference-скриншот (зависит от Source of Truth):
+   (a) Stitch → get_screen() → скачать screenshot через browser_subagent
+   (b) Figma → пользователь предоставляет экспорт PNG
+   (c) HTML-ref → открыть HTML-файл в browser_subagent → capture_screenshot
+
+2. Получить actual-скриншот:
+   → browser_subagent: открыть реализацию → capture_screenshot
+
+3. Визуально сравнить (Tester анализирует оба скриншота):
+   → Структура: элементы на местах?
+   → Типографика: шрифт, размер, цвет?
+   → Spacing: отступы соответствуют?
+   → Цвета: палитра верна?
+   → Состояния: все реализованы?
+
+4. Оформить finding:
+   → UX-PARITY-xx: PASS / FAIL + скриншот + описание
+```
+
+### Пример: Stitch как Source of Truth
+
+```
+Шаг 1: get_screen(projectId, screenId) → получить screenshot URL
+Шаг 2: browser_subagent → открыть screenshot URL → capture_screenshot → сохранить как reference
+Шаг 3: browser_subagent → открыть реализацию (Wix Dashboard) → capture_screenshot → сохранить как actual
+Шаг 4: Сравнить reference vs actual → зафиксировать расхождения
+```
+
+### Пример: Figma как Source of Truth
+
+```
+Шаг 1: Пользователь предоставляет PNG экспорт из Figma
+Шаг 2: browser_subagent → открыть реализацию → capture_screenshot
+Шаг 3: Сравнить Figma PNG vs actual screenshot
+Шаг 4: Оформить findings
+```
+
+### Пример: HTML-ref как Source of Truth
+
+```
+Шаг 1: browser_subagent → открыть popup_templates/glassmorphism.html → capture_screenshot
+Шаг 2: browser_subagent → открыть реализацию → capture_screenshot
+Шаг 3: Сравнить reference vs actual
+Шаг 4: Оформить findings
+```
+
+---
+
+## DEMO Gate через Browser
+
+### Протокол DEMO-xx
+
+```
+1. Получить DEMO-инструкции от Dev (DEMO-xx)
+2. Pre-Auth (если Wix/Shopify) или открыть URL напрямую
+3. browser_subagent: выполнить шаги из DEMO
+4. capture_screenshot на КАЖДОМ шаге
+5. Зафиксировать: PASS/FAIL + скриншот + описание
+6. Embed в walkthrough.md
+```
+
+### Формат evidence
+
+```markdown
+### DEMO-01: Template Selection
+
+![Step 1: Open editor](path/to/screenshot_step1.png)
+Статус: ✅ PASS — редактор открылся, шаблоны загрузились
+
+![Step 2: Select Glassmorphism](path/to/screenshot_step2.png)
+Статус: ✅ PASS — preview обновился корректно
+
+![Step 3: Save changes](path/to/screenshot_step3.png)
+Статус: ❌ FAIL — toast не появился после сохранения
+```
+
+---
+
+## browser_subagent Best Practices
+
+### Правила вызова
+
+```
+browser_subagent(
+  Task: "Detailed description of what to check and what to return",
+  TaskName: "Short descriptive name",
+  RecordingName: "lowercase_with_underscores"
+)
+```
+
+### Что указывать в Task
+
+- **Конкретные элементы** для проверки (data-testid, текст, CSS)
+- **Ожидаемый результат** (что должно быть видно)
+- **Условие возврата** (когда считать задачу завершённой)
+- **Скриншоты** — когда именно их делать
+
+### Пример хорошего Task
+
+```
+Navigate to the Widget Design page. Verify that:
+1. Template selector shows at least 3 templates
+2. Click on "Glassmorphism" template
+3. Verify live preview updates with glassmorphism styling
+4. Take a screenshot after each step.
+Return: screenshot paths and PASS/FAIL status for each step.
+```
+
+### Пример плохого Task ❌
+
+```
+Check if the page works.
+```
+
+---
+
+## Anti-patterns
+
+- ❌ `browser_subagent` без конкретных шагов — «проверь страницу» слишком размыто
+- ❌ Открывать новые URL после Pre-Auth — потеряем auth state
+- ❌ Не делать скриншоты — нет evidence = нет proof
+- ❌ Визуальная проверка без reference — нужен baseline (Stitch/Figma/HTML)
+- ❌ Игнорировать `.webp` записи — это готовый evidence
+- ❌ Тестировать бизнес-логику через browser — используй unit-тесты
+
+---
+
+## Артефакты (Deliverables)
+
+| Артефакт | Формат | Где |
+|----------|--------|-----|
+| Скриншоты шагов | `.png` | Embed в walkthrough.md |
+| Видео-записи | `.webp` | Embed в walkthrough.md |
+| DEMO Results | Таблица | В QA Report |
+| UX Parity Results | Таблица | В QA Report |
+| Findings | P0/P1/P2 блоки | В QA Report |
+
+---
+
+## Выход (формат)
+
+### Browser Test Summary
+| Step | Action | Expected | Actual | Screenshot | Status |
+|------|--------|----------|--------|------------|--------|
+| 1 | ... | ... | ... | 📸 link | PASS/FAIL |
+
+### UX Parity Results
+| UX-PARITY-xx | Screen | Source of Truth | Findings | Status |
+|--------------|--------|----------------|----------|--------|
+| ... | ... | Stitch / Figma / HTML-ref | ... | PASS/FAIL |
+
+### DEMO Results
+| DEMO-xx | Steps verified | Issues | Status |
+|---------|---------------|--------|--------|
+| ... | 5/5 | none | ✅ PASS |

package/.agents/qa_browser_testing/agents/claude.json

@@ -0,0 +1,19 @@
+{
+  "name": "qa_browser_testing",
+  "display_name": "Antigravity Browser Testing",
+  "description": "Визуальное E2E-тестирование через встроенный Antigravity Browser — Pre-Auth Handoff, browser_subagent, скриншоты, visual parity, evidence-сбор.",
+  "default_prompt": "Используй $qa_browser_testing, когда задача относится к навыку \"Antigravity Browser Testing\".",
+  "triggers": [
+    "qa_browser_testing",
+    "qa browser testing",
+    "Antigravity Browser Testing",
+    "Визуальное E2E-тестирование через встроенный Antigravity Browser — Pre-Auth Handoff, browser_subagent, скриншоты, visual parity, evidence-сбор"
+  ],
+  "capabilities": [
+    "qa",
+    "browser",
+    "testing"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/.agents/qa_browser_testing/agents/copilot.json

@@ -0,0 +1,19 @@
+{
+  "name": "qa_browser_testing",
+  "display_name": "Antigravity Browser Testing",
+  "description": "Визуальное E2E-тестирование через встроенный Antigravity Browser — Pre-Auth Handoff, browser_subagent, скриншоты, visual parity, evidence-сбор.",
+  "default_prompt": "Используй $qa_browser_testing, когда задача относится к навыку \"Antigravity Browser Testing\".",
+  "triggers": [
+    "qa_browser_testing",
+    "qa browser testing",
+    "Antigravity Browser Testing",
+    "Визуальное E2E-тестирование через встроенный Antigravity Browser — Pre-Auth Handoff, browser_subagent, скриншоты, visual parity, evidence-сбор"
+  ],
+  "capabilities": [
+    "qa",
+    "browser",
+    "testing"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/.agents/qa_browser_testing/agents/gemini.json

@@ -0,0 +1,19 @@
+{
+  "name": "qa_browser_testing",
+  "display_name": "Antigravity Browser Testing",
+  "description": "Визуальное E2E-тестирование через встроенный Antigravity Browser — Pre-Auth Handoff, browser_subagent, скриншоты, visual parity, evidence-сбор.",
+  "default_prompt": "Используй $qa_browser_testing, когда задача относится к навыку \"Antigravity Browser Testing\".",
+  "triggers": [
+    "qa_browser_testing",
+    "qa browser testing",
+    "Antigravity Browser Testing",
+    "Визуальное E2E-тестирование через встроенный Antigravity Browser — Pre-Auth Handoff, browser_subagent, скриншоты, visual parity, evidence-сбор"
+  ],
+  "capabilities": [
+    "qa",
+    "browser",
+    "testing"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/.agents/qa_browser_testing/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "Antigravity Browser Testing"
+  short_description: "Визуальное E2E-тестирование через встроенный Antigravity Browser — Pre-Auth Handoff, browser_su…"
+  default_prompt: "Используй $qa_browser_testing, когда задача относится к навыку \"Antigravity Browser Testing\"."
+dependencies:
+  tools: []
+policy:
+  allow_implicit_invocation: true

package/.agents/qa_browser_testing/agents/qwen.json

@@ -0,0 +1,19 @@
+{
+  "name": "qa_browser_testing",
+  "display_name": "Antigravity Browser Testing",
+  "description": "Визуальное E2E-тестирование через встроенный Antigravity Browser — Pre-Auth Handoff, browser_subagent, скриншоты, visual parity, evidence-сбор.",
+  "default_prompt": "Используй $qa_browser_testing, когда задача относится к навыку \"Antigravity Browser Testing\".",
+  "triggers": [
+    "qa_browser_testing",
+    "qa browser testing",
+    "Antigravity Browser Testing",
+    "Визуальное E2E-тестирование через встроенный Antigravity Browser — Pre-Auth Handoff, browser_subagent, скриншоты, visual parity, evidence-сбор"
+  ],
+  "capabilities": [
+    "qa",
+    "browser",
+    "testing"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/.agents/qa_browser_testing/agents/skill.yaml

@@ -0,0 +1,23 @@
+version: 1
+name: "qa_browser_testing"
+display_name: "Antigravity Browser Testing"
+description: "Визуальное E2E-тестирование через встроенный Antigravity Browser — Pre-Auth Handoff, browser_subagent, скриншоты, visual parity, evidence-сбор."
+default_prompt: "Используй $qa_browser_testing, когда задача относится к навыку \"Antigravity Browser Testing\"."
+triggers:
+  - "qa_browser_testing"
+  - "qa browser testing"
+  - "Antigravity Browser Testing"
+  - "Визуальное E2E-тестирование через встроенный Antigravity Browser — Pre-Auth Handoff, browser_subagent, скриншоты, visual parity, evidence-сбор"
+capabilities:
+  - "qa"
+  - "browser"
+  - "testing"
+tools: []
+invocation:
+  explicit: true
+  implicit: true
+localization:
+  default_locale: "ru"
+  available_locales:
+    - "ru"
+    - "en"

package/.agents/qa_e2e_playwright/SKILL.md

@@ -0,0 +1,313 @@
+---
+name: qa_e2e_playwright
+description: E2E-тестирование через Playwright для CI/CD — автоматизированные spec-файлы, page objects, visual regression, pipeline интеграция. Для ручного тестирования в Antigravity → $qa_browser_testing.
+last_verified: 2026-03-11
+version: 2.0
+---
+
+# Skill: E2E Playwright (CI/CD Automated)
+
+## Назначение
+
+Автоматизированный E2E regression suite через **Playwright** для CI/CD pipeline.
+Page Objects, spec-файлы, visual snapshot comparison, GitHub Actions.
+
+> [!IMPORTANT]
+> Этот скил — для **автоматизированных тестов в CI/CD**.
+> Для интерактивного тестирования в Google Antigravity → `$qa_browser_testing`.
+
+---
+
+## Когда использовать
+
+- Проект дорос до CI/CD pipeline c E2E gate
+- Нужен автоматический regression на каждый PR/deploy
+- Visual regression: pixel-perfect сравнение в CI
+- Стабильный UI, который не будет часто flaky
+
+## Когда НЕ использовать
+
+- Тестирование внутри Antigravity → `$qa_browser_testing`
+- Wix/Shopify sandbox (нет доступа из CI) → `$qa_browser_testing`
+- Unit/integration → Vitest
+- Первый срез / нестабильный UI → тесты будут flaky
+
+---
+
+## Стек проекта (SCR)
+
+| Компонент | Технология | Расположение |
+|-----------|-----------|-------------|
+| Unit/Integration | **Vitest** | `apps/*/vitest.config.js` |
+| E2E | **Playwright** | `apps/dashboard/e2e/` (создать) |
+| Wix Test Utils | `@wix/wix-ui-test-utils` | В node_modules |
+| Wix UniDriver | `@wix/unidriver-playwright` | В node_modules |
+
+---
+
+## Setup
+
+### 1. Установка
+
+```bash
+cd apps/dashboard
+npm init playwright@latest -- --yes --browser=chromium --lang=js
+```
+
+### 2. Конфигурация: `playwright.config.js`
+
+```js
+// apps/dashboard/playwright.config.js
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  timeout: 30_000,
+  expect: { timeout: 5_000 },
+  fullyParallel: false,
+  retries: process.env.CI ? 2 : 0,
+  workers: 1,
+  reporter: [['html', { open: 'never' }], ['list']],
+
+  use: {
+    baseURL: process.env.BASE_URL || 'https://manage.wix.com',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+    video: 'on-first-retry',
+  },
+
+  projects: [
+    {
+      name: 'wix-dashboard',
+      use: { ...devices['Desktop Chrome'] },
+    },
+  ],
+});
+```
+
+### 3. Структура директории
+
+```
+apps/dashboard/e2e/
+├── fixtures/
+│   ├── auth.fixture.js      # Auth (storageState)
+│   └── test-data.js          # Тестовые данные
+├── pages/
+│   ├── BasePage.js            # Base page object
+│   ├── WidgetDesignPage.js    # Widget Design Editor
+│   ├── RulesTriggersPage.js   # Rules & Triggers
+│   └── CouponsPage.js         # Coupons Management
+├── specs/
+│   ├── widget-design.spec.js  # Widget editor E2E
+│   ├── coupon-flow.spec.js    # Coupon CRUD
+│   └── visual-parity.spec.js  # Screenshot comparison
+└── screenshots/
+    └── expected/              # Baseline скриншоты
+```
+
+---
+
+## Page Object Model
+
+### BasePage
+
+```js
+/**
+ * Базовый page object для всех страниц dashboard.
+ */
+export class BasePage {
+  /**
+   * @param {import('@playwright/test').Page} page - Playwright page instance.
+   */
+  constructor(page) {
+    this.page = page;
+  }
+
+  /**
+   * Ожидает загрузку страницы.
+   * @param {string} contentSelector - CSS-селектор основного контента.
+   * @param {number} [timeout=10000] - таймаут ожидания в мс.
+   */
+  async waitForPageLoad(contentSelector, timeout = 10_000) {
+    await this.page.waitForSelector(contentSelector, {
+      state: 'visible',
+      timeout,
+    });
+  }
+
+  /**
+   * Делает скриншот компонента для visual parity.
+   * @param {string} name - имя скриншота.
+   * @returns {Promise<Buffer>} скриншот.
+   */
+  async takeScreenshot(name) {
+    return this.page.screenshot({
+      path: `e2e/screenshots/actual/${name}.png`,
+      fullPage: true,
+    });
+  }
+}
+```
+
+---
+
+## Тест-паттерны
+
+### Happy Path
+
+```js
+import { test, expect } from '@playwright/test';
+import { WidgetDesignPage } from '../pages/WidgetDesignPage.js';
+
+test.describe('Widget Design Editor', () => {
+  test('should select template and save', async ({ page }) => {
+    const editor = new WidgetDesignPage(page);
+    await editor.waitForPageLoad('[data-testid="widget-editor"]');
+    await editor.selectTemplate('Glassmorphism');
+    await editor.fillFields({ headline: 'Special Offer!', coupon: 'SAVE20' });
+    await editor.save();
+
+    await expect(editor.livePreview).toContainText('Special Offer!');
+  });
+});
+```
+
+### Error Path
+
+```js
+test('should show validation error for empty coupon', async ({ page }) => {
+  const editor = new WidgetDesignPage(page);
+  await editor.waitForPageLoad('[data-testid="widget-editor"]');
+  await editor.fillFields({ coupon: '' });
+  await editor.save();
+
+  const error = page.locator('[data-testid="coupon-error"]');
+  await expect(error).toBeVisible();
+});
+```
+
+### UI States
+
+```js
+test('should show empty state when no templates', async ({ page }) => {
+  await page.route('**/api/templates', (route) =>
+    route.fulfill({ status: 200, body: '[]', headers: { 'Content-Type': 'application/json' } }),
+  );
+  await page.reload();
+  await expect(page.locator('[data-testid="empty-state"]')).toContainText('No templates');
+});
+```
+
+---
+
+## Visual Regression
+
+> [!IMPORTANT]
+> **Source of truth определяется UX Designer** (обязательный вопрос #2).
+> Baseline-скриншоты зависят от выбранного источника.
+
+```js
+test('visual parity: popup matches design', async ({ page }) => {
+  await page.goto('/preview/glassmorphism');
+  const popup = page.locator('[data-testid="popup-container"]');
+  await expect(popup).toHaveScreenshot('glassmorphism-popup.png', {
+    maxDiffPixelRatio: 0.05,
+    threshold: 0.2,
+  });
+});
+```
+
+```bash
+# Обновить baseline
+npx playwright test --update-snapshots
+```
+
+---
+
+## Naming Convention
+
+```
+[feature].spec.js             — тесты
+[feature].visual.spec.js      — visual regression
+[PageName].js                  — page objects
+
+# Test IDs (data-testid)
+[component]-[element]          → popup-container
+[component]-[element]-[state]  → save-button-disabled
+```
+
+> [!WARNING]
+> DEV обязан добавить `data-testid` для всех интерактивных элементов.
+
+---
+
+## Запуск
+
+```bash
+npx playwright test                              # Все
+npx playwright test e2e/specs/widget-design.spec.js  # Один spec
+npx playwright test --ui                         # Debug UI
+npx playwright test --headed                     # Headed
+npx playwright test --update-snapshots           # Обновить baseline
+npx playwright show-report                       # Отчёт
+```
+
+---
+
+## CI/CD Pipeline
+
+```yaml
+# .github/workflows/e2e.yml
+e2e-tests:
+  runs-on: ubuntu-latest
+  steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-node@v4
+      with: { node-version: 20 }
+    - run: npm ci
+      working-directory: apps/dashboard
+    - run: npx playwright install --with-deps chromium
+      working-directory: apps/dashboard
+    - run: npx playwright test
+      working-directory: apps/dashboard
+    - uses: actions/upload-artifact@v4
+      if: failure()
+      with:
+        name: playwright-report
+        path: apps/dashboard/playwright-report/
+```
+
+---
+
+## Anti-patterns
+
+- ❌ CSS-селекторы (`.class-name`) — хрупко, только `data-testid`
+- ❌ `page.waitForTimeout(3000)` — использовать `waitForSelector`
+- ❌ E2E для логики, покрытой unit-тестами — избыточно
+- ❌ Зависимость тестов друг от друга — каждый тест изолирован
+- ❌ Hard-coded данные в спеках — выносить в `fixtures/test-data.js`
+- ❌ Игнорировать flaky — стабилизировать или удалить
+- ❌ Скриншот всей страницы — скриншотить **конкретный компонент**
+
+---
+
+## Definition of Done
+
+- [ ] Critical flows из Test Plan покрыты E2E
+- [ ] Каждый тест: happy path + ≥1 error path
+- [ ] Page Objects для ключевых страниц
+- [ ] `data-testid` добавлены (DEV)
+- [ ] Baseline-скриншоты согласованы
+- [ ] Нет flaky (3 прогона стабильно)
+- [ ] CI pipeline настроен
+- [ ] Команда запуска в README
+
+---
+
+## Deliverables
+
+- Spec-файлы: `apps/dashboard/e2e/specs/`
+- Page Objects: `apps/dashboard/e2e/pages/`
+- `playwright.config.js`
+- CI/CD pipeline config
+- Список `data-testid` (запрос к DEV)