symfonia-ai-tools 1.0.0

package/templates/packs/laravel/_ai/skills/testing-unit/SKILL.md

@@ -0,0 +1,200 @@
+# Skill: Laravel Unit Tests
+
+## Trigger
+Use when writing unit tests — isolated class tests without database, HTTP, or Laravel container.
+
+## File Location & Namespace
+
+- `Modules/{Module}/Tests/Unit/{Subdirectory}/{ClassName}Test.php`
+- Namespace mirrors path: `Modules\{Module}\Tests\Unit\{Subdirectory}`
+- Subdirectory should reflect what is being tested: `Services/`, `Listeners/`, `Export/`, `DTO/`, etc.
+
+## Base Class
+
+Unit tests extend `PHPUnit\Framework\TestCase` — **not** `Tests\TestCase`:
+```php
+use PHPUnit\Framework\TestCase;
+
+class MyServiceTest extends TestCase
+```
+
+Unit tests must **never** touch the database, make HTTP requests, or boot the Laravel application. If you need any of these, write a Feature test instead.
+
+## When to Use Unit vs Feature Tests
+
+| Use Unit Test when... | Use Feature Test when... |
+|---|---|
+| Testing pure logic (calculations, transformations) | Testing with real database (Eloquent, repositories) |
+| Testing a class in isolation with mocked dependencies | Testing HTTP endpoints (controllers) |
+| Testing event/listener logic without dispatching | Testing service integration with real DB |
+| Testing DTOs, value objects, enums | Testing permissions, auth, middleware |
+| No Laravel container needed | Laravel container / `app()` needed |
+
+## Test Structure
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace Modules\{Module}\Tests\Unit\{Subdirectory};
+
+use PHPUnit\Framework\TestCase;
+
+class {ClassName}Test extends TestCase
+{
+    private SomeDependency $dependency;
+    private MyService $service;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $this->dependency = $this->createMock(SomeDependency::class);
+        $this->service = new MyService($this->dependency);
+    }
+
+    // --- public test methods ---
+
+    public function test_method_returns_expected_result(): void
+    {
+        $this->dependency->expects($this->once())
+            ->method('getData')
+            ->with(42)
+            ->willReturn('result');
+
+        $result = $this->service->process(42);
+
+        $this->assertSame('expected', $result);
+    }
+
+    // --- private helpers at BOTTOM ---
+
+    private function createSomeFixture(): SomeClass
+    {
+        // ...
+    }
+}
+```
+
+## Required Conventions
+
+### Method naming
+- Prefix: `test_` + `snake_case` description
+- No `@test` annotation
+- All methods must have explicit return type (`: void` for tests)
+
+### Class structure order
+1. Properties
+2. `setUp()` / `tearDown()`
+3. All `public` test methods
+4. All `private` helper methods — **always at the bottom**
+
+### PHP standards
+- `declare(strict_types=1)` at top
+- All namespaces as FQN/import statements
+- All closure parameters must be typed
+
+## Mocking Approaches
+
+### PHPUnit `createMock` (preferred)
+
+```php
+private SomeRepository $repository;
+
+protected function setUp(): void
+{
+    parent::setUp();
+    $this->repository = $this->createMock(SomeRepository::class);
+    $this->service = new MyService($this->repository);
+}
+
+public function test_calls_repository_with_correct_args(): void
+{
+    $this->repository->expects($this->once())
+        ->method('findById')
+        ->with(42)
+        ->willReturn($entity);
+
+    $this->service->process(42);
+}
+```
+
+### Mockery (when PHPUnit mocks are insufficient)
+
+```php
+use Mockery;
+use Mockery\Adapter\Phpunit\MockeryPHPUnitIntegration;
+use PHPUnit\Framework\TestCase;
+
+class MyTest extends TestCase
+{
+    use MockeryPHPUnitIntegration;
+
+    public function test_something(): void
+    {
+        $mock = Mockery::mock(SomeClass::class);
+        $mock->shouldReceive('method')->once()->andReturn('value');
+        // ...
+    }
+}
+```
+
+### Mocking Eloquent Models
+
+```php
+private function createUserMock(int $id, string $name): User
+{
+    $user = $this->getMockBuilder(User::class)
+        ->onlyMethods(['notify'])
+        ->getMock();
+
+    $user->setAttribute(User::COLUMN_ID, $id);
+    $user->setAttribute(User::COLUMN_NAME, $name);
+
+    return $user;
+}
+```
+
+## Data Providers
+
+```php
+/**
+ * @dataProvider invalidInputProvider
+ */
+public function test_throws_on_invalid_input(mixed $input): void
+{
+    $this->expectException(InvalidArgumentException::class);
+    $this->service->process($input);
+}
+
+public static function invalidInputProvider(): array
+{
+    return [
+        'null' => [null],
+        'empty string' => [''],
+        'negative number' => [-1],
+    ];
+}
+```
+
+Data provider methods **must** be `public static`.
+
+## Things to Avoid
+
+- **No database access** — if you need DB, write a Feature test
+- **No `app()` or service container** — instantiate classes manually with mocked deps
+- **No HTTP requests** — that's Feature test territory
+- **No `Event::fake()` or `Mail::fake()`** — those are Laravel facade fakes for Feature tests
+- **No `Tests\TestCase`** — only use `PHPUnit\Framework\TestCase`
+- **No meaningless test data** — avoid "test", "foo", "bar"; use realistic values
+
+## Running Tests
+
+```bash
+# Single test class
+docker exec {{DOCKER_CONTAINER}} php artisan test --filter='{TestClassName}'
+
+# Unit tests only for a module
+docker exec {{DOCKER_CONTAINER}} php artisan test --filter='Modules\\{Module}\\Tests\\Unit'
+```

package/templates/packs/laravel/_guidelines.md

@@ -0,0 +1,25 @@
+
+
+---
+
+## Laravel + PHP
+
+### Core Principle
+Follow Laravel conventions first. Use [official docs](https://laravel.com/docs).
+
+### PHP Standards
+- PER 3.0 coding style, `declare(strict_types=1)` everywhere
+- FQN imports, `?string` not `string|null`, `void` return types
+- Typed properties over docblocks, constructor property promotion
+
+### Architecture
+- SOLID, especially Single Responsibility
+- No business logic in controllers
+- Repository pattern for data access (CQRS: Command/Query repos)
+- Events + Listeners for decoupled communication
+- Dependency injection, no static calls
+
+### Testing
+- PHPUnit with data providers and factories
+- Laravel fakes for Mail, Queue, Notification, Storage
+- See `.ai/instructions/testing.instructions.md`

package/templates/packs/laravel/pack.json

@@ -0,0 +1,6 @@
+{
+  "name": "Laravel + PHP",
+  "description": "Moduly, CQRS, API Resources, PHPUnit",
+  "default": false,
+  "placeholders": {}
+}

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

@@ -0,0 +1,219 @@
+---
+applyTo: "**/*.spec.ts"
+---
+
+# Playwright E2E Testing Instructions
+
+## File and Directory Naming
+
+```
+Directories:  NN_Name_Module/        (e.g., tests/20_Tasks/)
+Sections:     NN_NN_Name_Section/    (e.g., tests/20_Tasks/20_01_Other/)
+Test files:   NN_NN_NN_Name.spec.ts  (e.g., 20_01_06_Draft_version.spec.ts)
+```
+
+## data-testid Convention (kebab-case)
+
+```
+Structure: "{module}-{action}-{element-type}"
+
+Correct:
+  data-testid="task-add-save-button"
+  data-testid="task-title-input"
+  data-testid="task-acceptance-checkbox"
+
+Wrong:
+  data-testid="addTaskButton"        (camelCase)
+  data-testid="task_add_button"      (snake_case)
+  data-testid="save-button"          (missing module)
+```
+
+### Dynamic data-testid
+```vue
+:data-testid="`task-row-${index}`"
+:data-testid="`task-user-${user.id}-checkbox`"
+```
+
+## Test Structure
+
+```typescript
+import { test, expect } from '@playwright/test';
+import { PageObject } from '../../pages/PageObject';
+
+test.describe('Module: Feature name', { tag: ['@module', '@verified'] }, () => {
+    let page: PageObject;
+
+    test.beforeEach(async ({ page: browserPage }) => {
+        page = new PageObject(browserPage);
+        // Login and setup
+    });
+
+    test('Feature: Specific scenario', async () => {
+        await test.step('Fill form with data', async () => {
+            // Arrange + Act
+        });
+
+        await test.step('Navigate and verify', async () => {
+            // Act
+        });
+
+        await test.step('Validate results', async () => {
+            // Assert
+        });
+    });
+});
+```
+
+## Selector Priorities
+
+```typescript
+// 1. data-testid (PREFERRED)
+this.page.locator('[data-testid="task-add-button"]')
+
+// 2. ID (if unique)
+this.page.locator('#taskTitle')
+
+// 3. Semantic attributes
+this.page.locator('input[type="email"]')
+
+// 4. CSS classes (LAST RESORT)
+this.page.locator('.btn-primary')  // Avoid
+```
+
+## Page Object Model (POM)
+
+```typescript
+import { Page, Locator, expect } from '@playwright/test';
+
+export class TasksPage {
+    protected page: Page;
+
+    private readonly addButton: Locator;
+    private readonly listTable: Locator;
+    private readonly searchInput: Locator;
+
+    constructor(page: Page) {
+        this.page = page;
+        this.addButton = this.page.locator('[data-testid="task-add-button"]');
+        this.listTable = this.page.locator('[data-testid="task-list-table"]');
+        this.searchInput = this.page.locator('[data-testid="task-search-input"]');
+    }
+
+    async visit(): Promise<void> {
+        await this.page.goto('/tasks');
+        await this.page.waitForLoadState('networkidle');
+    }
+
+    async addClick(): Promise<void> {
+        await this.addButton.waitFor({ state: 'visible', timeout: 10000 });
+        await this.addButton.click();
+    }
+
+    async search(name: string): Promise<void> {
+        await this.searchInput.fill(name);
+        await this.searchInput.press('Enter');
+    }
+
+    async shouldBeOnList(name: string): Promise<void> {
+        const row = this.listTable.locator('[data-testid*="task-row"]', { hasText: name });
+        await expect(row).toBeVisible({ timeout: 10000 });
+    }
+}
+```
+
+### POM Rules
+- Locators **PRIVATE** - don't export directly
+- Methods **PUBLIC** - only actions and validations
+- Use getters for dynamic locators
+- Always add timeout to `waitFor()`
+- Use `expect()` inside validation methods
+
+## Timeouts and Waiting
+
+```typescript
+// PREFERRED: waitFor with specific state
+await element.waitFor({ state: 'visible', timeout: 10000 });
+
+// Wait for URL
+await page.waitForURL('**/tasks/**', { timeout: 15000 });
+
+// Wait for network
+await page.waitForLoadState('networkidle');
+
+// Wait for response
+const responsePromise = page.waitForResponse('**/api/tasks/**');
+await button.click();
+const response = await responsePromise;
+
+// AVOID: Only when no alternative
+await page.waitForTimeout(2000);
+```
+
+## Assertions
+
+```typescript
+await expect(page).toHaveURL(/.*tasks/);
+await expect(element).toBeVisible();
+await expect(element).toBeDisabled();
+await expect(element).toHaveText('Done');
+await expect(element).toHaveCount(5);
+
+// Soft assertions (don't stop test)
+await expect.soft(element).toBeVisible();
+
+// Custom messages
+await expect(element, 'Task should be visible').toBeVisible();
+```
+
+## Test Tags
+
+```typescript
+{ tag: ['@module', '@verified'] }
+{ tag: ['@module', '@smoke'] }
+{ tag: ['@module', '@regression'] }
+```
+
+## What to AVOID
+
+```typescript
+// Hardcoded URLs
+await page.goto('https://example.com/tasks');  // Use baseURL
+
+// Hardcoded data
+const username = 'user@example.com';  // Use fixtures
+
+// CSS selectors first
+await page.locator('.btn-primary').click();  // Use data-testid
+
+// test.only() in commits
+test.only('should work', async () => {});  // Remove before commit
+
+// Code duplication
+await page.locator('[data-testid="btn"]').click();  // Use POM
+
+// Long timeouts without reason
+await page.waitForTimeout(10000);  // Use deterministic waits
+```
+
+## Pre-Commit Checklist
+
+- [ ] All tests pass locally
+- [ ] No `console.log()` or `debugger`
+- [ ] No `test.only()`
+- [ ] All `data-testid` follow kebab-case convention
+- [ ] POMs follow structure
+- [ ] Tags added correctly
+- [ ] TypeScript compiles without errors
+- [ ] Imports organized
+
+## Running Tests
+
+```bash
+cd {{PLAYWRIGHT_DIR}} && \
+  BASE_URL="{{BASE_URL}}" \
+  npx playwright test tests/path/to/test.spec.ts \
+  --project=chromium --workers=1 --retries=0
+```
+
+- Use `--workers=1 --retries=0` for debugging
+- Use `--workers=2 --retries=1` for confirmed tests

package/templates/packs/playwright/_ai/skills/playwright/README.md

@@ -0,0 +1,194 @@
+# Playwright Testing Skill
+
+**Expert guidance for running, debugging, and refactoring EXISTING Playwright E2E tests**
+
+## What This Skill Does
+
+This skill helps with **EXISTING tests** - running, debugging, analyzing, and refactoring already written Playwright tests.
+
+## Quick Facts
+
+| Aspect | Details |
+|--------|---------|
+| **Purpose** | Work with EXISTING tests (already written) |
+| **Input** | Existing test file (TypeScript) |
+| **Output** | Test results, debugging info, refactored code |
+| **Use cases** | Run tests, debug failures, refactor code, analyze coverage |
+
+## When to Use This Skill
+
+**Use `playwright` when**:
+- **Converting recorded test from `tmp/`** (after `playwright-record`)
+- Running existing tests
+- Debugging test failures
+- Refactoring test code
+- Analyzing test results
+- Improving test quality
+- Test already exists in `{{PLAYWRIGHT_DIR}}/tests/` or `{{PLAYWRIGHT_DIR}}/tmp/`
+
+**Use `playwright-record` skill instead when**:
+- Need to RECORD a NEW test by clicking in browser
+- No test exists yet
+- Want to capture user flow
+
+## Converting Tests from tmp/
+
+**CRITICAL**: When converting recorded tests, this skill:
+
+1. **Checks existing Page Objects FIRST** (no duplication!)
+2. Reuses existing POMs (LoginPage, DashboardPage, etc.)
+3. Creates NEW POMs only when needed
+4. Converts JavaScript to TypeScript
+5. Adds proper assertions
+6. Moves to production `tests/` directory
+7. **RUNS test to verify it works** (using Makefile or npx)
+8. **DEBUGS failures** if test doesn't pass
+9. **FIXES issues** in Page Objects or test code
+10. **RE-RUNS** until test passes
+
+**Example**:
+```
+User: "Convert tmp/playwright-test-mytest.js"
+
+AI Process:
+1. Check existing POMs -> LoginPage exists
+2. Reuse LoginPage + Create MyFeaturePage
+3. Convert to TypeScript test
+4. Move to tests/NN_Module/NN_NN_NN_Name.spec.ts
+5. RUN: {{RUN_TEST_COMMAND}} playwright_spec_file="tests/.../test.spec.ts"
+6. IF FAILS: Check screenshot, analyze error
+7. FIX: Update selectors/waits in Page Object
+8. RE-RUN: Until test passes
+```
+
+## Test Verification Methods
+
+**After converting test, ALWAYS verify using one of these methods:**
+
+### Method 1: Makefile + Docker (Recommended)
+
+```bash
+# Run specific test
+{{RUN_TEST_COMMAND}} playwright_spec_file="{{PLAYWRIGHT_DIR}}/tests/{{MODULE_PATH}}/{{TEST_FILE}}.spec.ts"
+
+# Run with tags
+{{RUN_TEST_COMMAND}} playwright_grep_tags="@{{MODULE_TAG}}"
+
+# Run with retries disabled (for debugging)
+{{RUN_TEST_COMMAND}} \
+  playwright_spec_file="{{PLAYWRIGHT_DIR}}/tests/{{MODULE_PATH}}/{{TEST_FILE}}.spec.ts" \
+  playwright_retries="0"
+```
+
+### Method 2: Local npx (Development)
+
+```bash
+cd {{PLAYWRIGHT_DIR}}
+
+# Run test
+npx playwright test tests/{{MODULE_PATH}}/{{TEST_FILE}}.spec.ts
+
+# Debug mode (step through)
+npx playwright test tests/{{MODULE_PATH}}/{{TEST_FILE}}.spec.ts --debug
+
+# UI mode (interactive)
+npx playwright test tests/{{MODULE_PATH}}/{{TEST_FILE}}.spec.ts --ui
+
+# Headed mode (see browser)
+npx playwright test tests/{{MODULE_PATH}}/{{TEST_FILE}}.spec.ts --headed
+```
+
+## Debugging Failed Tests
+
+**When test fails:**
+
+1. **Check artifacts:**
+   - Screenshots: `{{PLAYWRIGHT_DIR}}/test-results/[test-name]/test-failed-1.png`
+   - HTML Report: `npx playwright show-report` (in {{PLAYWRIGHT_DIR}}/)
+
+2. **Analyze error:**
+   - Timeout -> Add `waitFor({ state: 'visible' })`
+   - Selector not found -> Check data-testId in screenshot
+   - Navigation issue -> Add waits between steps
+
+3. **Fix code:**
+   - Update Page Object methods
+   - Add proper waits
+   - Fix selectors
+
+4. **Re-run until passes:**
+   ```bash
+   {{RUN_TEST_COMMAND}} playwright_spec_file="tests/..."
+   ```
+
+## Key Capabilities
+
+### Test Execution
+- Run tests with specific tags
+- Run tests in specific browsers
+- Run tests in headed/headless mode
+- Generate reports (HTML, JSON, JUnit)
+
+### Debugging
+- Analyze test failures
+- Identify flaky tests
+- Fix selector issues
+- Adjust timeouts and waits
+
+### Refactoring
+- Extract Page Objects
+- Create reusable helpers
+- Optimize selectors
+- Add missing assertions
+- Improve test structure
+
+### Analysis
+- Coverage reports
+- Performance metrics
+- Test reliability analysis
+
+## Difference from `playwright-record`
+
+| Aspect | `playwright` (THIS) | `playwright-record` |
+|--------|---------------------|---------------------|
+| **Purpose** | Work with EXISTING tests | CREATE NEW tests by recording |
+| **Input** | Test file (TypeScript) | User clicks in browser |
+| **Process** | Execute -> Debug -> Refactor | Record -> Convert -> Deploy |
+| **Output** | Test results, fixes | Production-ready test from clicks |
+| **User involvement** | None (or specify changes) | Clicking during recording |
+
+## Documentation
+
+**[SKILL.md](./SKILL.md)** - Complete documentation with:
+- Page Object Model patterns
+- Test organization structure
+- Selector strategies (data-testId)
+- Fixture management
+- Tagging strategies
+- Best practices
+
+## Quick Examples
+
+### Run specific test
+```bash
+npx playwright test tests/{{MODULE_PATH}}/
+```
+
+### Debug failing test
+```bash
+npx playwright test tests/{{MODULE_PATH}}/ --debug
+```
+
+### Run with specific tag
+```bash
+npx playwright test --grep @smoke
+```
+
+### Generate HTML report
+```bash
+npx playwright test --reporter=html
+```
+
+---
+
+**Remember**: Use this skill for EXISTING tests. For NEW tests, use `playwright-record` skill!