symfonia-ai-tools 1.0.0

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

@@ -0,0 +1,87 @@
+# Playwright Test Recording Skill
+
+**Record browser interactions and save raw test code to `tmp/` directory**
+
+## What This Skill Does
+
+This skill handles **RECORDING ONLY** - it captures your clicks and saves raw JavaScript to `tmp/`.
+
+**Conversion to production code** is handled by separate skill: `playwright/SKILL.md`
+
+## Quick Facts
+
+| Aspect | Details |
+|--------|---------|
+| **User involvement** | Only clicking in browser during recording |
+| **AI automation** | Launch Codegen, monitor recording, verify save |
+| **Input** | User clicks in browser + scenario description |
+| **Output** | Raw JavaScript file in `tmp/` directory |
+| **Does NOT do** | Conversion, Page Objects, assertions (use `playwright` skill) |
+
+## Workflow Breakdown
+
+### What AI Does (Automated)
+1. Setup environment and configuration
+2. Launch Codegen with proper URL
+3. Monitor recording process
+4. Verify raw JavaScript saved to `tmp/`
+
+### What User Does (Manual)
+1. Click in browser to perform scenario
+2. Close Playwright Inspector when done
+
+**User time**: 2-3 minutes
+**AI time**: 5-10 seconds
+**Output**: Raw `.js` file in `tmp/`
+
+## When to Use This Skill
+
+**Use `playwright-record` when**:
+- Creating a NEW test from scratch
+- Want to record user flow by clicking
+- Need to capture browser interactions
+
+**Use `playwright` skill instead when**:
+- Need to CONVERT raw test to production code
+- Need to create Page Objects
+- Want to add assertions
+- Want to refactor existing test
+
+## Next Steps After Recording
+
+After recording completes, **AI ASKS if you want to continue**.
+
+**AI will ask:**
+> "Would you like me to convert this test to production code now?"
+
+**If you say YES:**
+- AI switches to `playwright` skill
+- Checks existing Page Objects (NO DUPLICATION!)
+- Converts JS to TS
+- Creates/updates POMs
+- Moves to `tests/`
+
+**If you say NO:**
+- Recording ends
+- Raw file stays in `tmp/`
+- You can convert later manually
+
+## Documentation
+
+**[SKILL.md](./SKILL.md)** - Complete documentation with:
+- Recording workflow
+- Configuration files
+- Real-world example
+- What happens after recording
+
+## Quick Start
+
+```bash
+# AI launches this automatically (you just click in browser)
+npx playwright codegen {{BASE_URL}}/login \
+  --output=tmp/playwright-test-mytest.js
+```
+
+---
+
+**Remember**: This skill only RECORDS. For conversion, use `playwright` skill!

package/templates/packs/playwright/_ai/skills/playwright-record/SKILL.md

@@ -0,0 +1,564 @@
+---
+name: playwright-record
+description: Guides users through recording and generating Playwright tests using Codegen tool. Helps convert recorded interactions into production-ready tests following project conventions, including proper Page Objects, data-testid selectors, and project structure.
+---
+
+# Playwright Test Recording
+
+Expert skill for recording Playwright tests and converting them into production-ready code that follows project testing standards.
+
+## When to Use This Skill
+
+Use this skill when the user:
+
+- Wants to record a new test scenario
+- Asks "how do I record a test?"
+- Says "generate test from browser interaction"
+- Wants to quickly prototype a test
+- Asks about Playwright Codegen
+- Needs help converting recorded test to POM pattern
+- Wants to capture complex user flows
+
+## Required Input
+
+- Start URL for the recording session (if not provided, ask the user to supply it before running Codegen).
+
+## What This Skill Does vs What User Does
+
+**This skill handles RECORDING ONLY** - it captures browser interactions and saves raw code to `{{PLAYWRIGHT_DIR}}/tmp`.
+
+**Conversion to production code is handled by `playwright/SKILL.md`** - separate skill for refactoring.
+
+### Recording Workflow Breakdown
+
+| **Step** | **What AI Does (Automated)** | **What User Does (Manual)** |
+|----------|------------------------------|------------------------------|
+| **1. Setup** | Checks if `{{PLAYWRIGHT_DIR}}/tmp` directory exists<br>Verifies `.env` and credentials configuration<br>Prepares output file path | Nothing |
+| **2. Launch Codegen** | Runs `npx playwright codegen <URL> --output={{PLAYWRIGHT_DIR}}/tmp/file.js`<br>Opens browser and Playwright Inspector<br>Monitors process status<br>If URL not provided, asks user to provide it before running Codegen | Nothing |
+| **3. Recording** | Monitors Codegen recording<br>Tracks generated code in real-time<br>Waits for user to finish | **Clicks in browser**<br>**Performs scenario steps**<br>**Closes Inspector when done** |
+| **4. Save Raw Code** | Verifies file was saved to `{{PLAYWRIGHT_DIR}}/tmp`<br>Shows path to recorded file<br>**ENDS HERE** | Nothing |
+
+### Summary: Scope of This Skill
+
+- **User**: Clicks in browser during recording (Step 3)
+- **AI**: Launches Codegen, monitors recording, verifies save
+- **Output**: Raw JavaScript file in `{{PLAYWRIGHT_DIR}}/tmp` directory
+- **Next step**: Use `playwright/SKILL.md` to convert raw code to production test
+
+**This skill does NOT:**
+- Convert JavaScript to TypeScript
+- Create Page Object Models
+- Add assertions
+- Move tests to production
+- **All conversion is done by `playwright/SKILL.md`**
+
+---
+
+## Difference Between This Skill and `playwright/SKILL.md`
+
+### `.github/skills/playwright-record/SKILL.md` (THIS FILE)
+
+**Purpose**: Record NEW tests by clicking in browser, then AUTO-CONVERT to production
+
+| Aspect | Description |
+|--------|-------------|
+| **When to use** | Creating a NEW test from scratch using browser interaction |
+| **Input** | User scenario description + User clicks in browser |
+| **Process** | Codegen -> Recording -> **AUTOMATIC CONVERSION** -> Production test |
+| **Output** | Clean TypeScript test in `tests/` with POMs, assertions, helpers |
+| **User involvement** | **Manual clicking during recording only** |
+| **AI involvement** | Setup, conversion, optimization, testing, deployment |
+
+### `.github/skills/playwright/SKILL.md`
+
+**Purpose**: Run, debug, refactor EXISTING tests
+
+| Aspect | Description |
+|--------|-------------|
+| **When to use** | Working with EXISTING tests (already written) |
+| **Input** | Existing test file (TypeScript) |
+| **Process** | Execute -> Analyze results -> Debug -> Refactor |
+| **Output** | Test results (pass/fail), debugging info, refactored code |
+| **User involvement** | None (or specifying what to change) |
+| **AI involvement** | Running tests, analyzing failures, suggesting fixes |
+
+### Quick Decision Guide
+
+**Use `playwright-record/SKILL.md` when**:
+- "I want to record a new test by clicking"
+- "Generate test from my browser interaction"
+- "I need to capture this user flow"
+- No test exists yet
+
+**Use `playwright/SKILL.md` when**:
+- "Run this test"
+- "Debug why this test is failing"
+- "Refactor this test to use Page Objects"
+- Test already exists in `tests/` or `tmp/`
+
+---
+
+## Real-World Workflow Example
+
+### Scenario: User wants to test a feature workflow
+
+**User says**:
+> "Record a test for adding a new item with sub-items"
+
+**AI executes (using THIS skill)**:
+
+#### Phase 1: Recording Setup (Automated)
+```bash
+# AI checks configuration
+- Verified tmp/ directory exists
+- Loaded .env configuration (BASE_URL, COMPANY_NAME)
+- Loaded credentials configuration
+
+# AI launches Codegen
+npx playwright codegen {{BASE_URL}}/login \
+  --output={{PLAYWRIGHT_DIR}}/tmp/playwright-test-feature-name.js
+```
+
+#### Phase 2: User Interaction (Manual)
+```
+AI: "Browser opened. Please perform these steps:"
+1. Login as admin
+2. Navigate to the target module/feature
+3. Perform the scenario actions
+4. Close Playwright Inspector when done
+
+USER: [clicks in browser following the steps]
+```
+
+#### Phase 3: Save and Verify (Automated)
+
+```bash
+# AI verifies file was saved
+- File saved: tmp/playwright-test-feature-name.js
+- File size: 1.2 KB
+- Contains 26 lines of code
+
+# AI reports
+- Recording completed!
+- Raw test saved to: tmp/playwright-test-feature-name.js
+```
+
+**AI output to user**:
+```
+Recording complete!
+
+Saved to: {{PLAYWRIGHT_DIR}}/tmp/playwright-test-feature-name.js
+
+Next steps:
+1. Review the recorded file
+2. To convert to production test, I can use playwright/SKILL.md
+
+Would you like me to convert this test to production code now?
+   - This will check existing Page Objects
+   - Create/update POMs only if needed
+   - Add proper TypeScript structure and assertions
+   - Move to tests/ directory
+
+Reply "yes" to continue with conversion, or "no" to stop here.
+```
+
+**Total time**:
+- User clicking: 2-3 minutes
+- AI setup/monitoring: 5-10 seconds
+- Result: Raw JavaScript file ready for conversion
+
+---
+
+### What Happens Next?
+
+**This skill STOPS here and ASKS user.**
+
+**If user confirms**, skill switches to `playwright/SKILL.md`:
+- Read raw JavaScript from `tmp/`
+- **Check existing Page Objects** (IMPORTANT: don't duplicate!)
+- Convert to TypeScript
+- Reuse existing POMs or create new ones
+- Add assertions
+- Move to `tests/` directory
+
+**Separation of concerns:**
+- `playwright-record` = **RECORDING** -> ask for confirmation
+- `playwright` = **CONVERSION & TESTING** -> only if user confirms
+
+---
+
+## Recording Tests with Codegen
+
+### Workflow for Recorded Tests
+
+**Directory Structure for Temporary Tests**:
+```
+{{PLAYWRIGHT_DIR}}/
+├── tmp/                                # Temporary/recorded tests (gitignored)
+│   ├── playwright-test-login.js       # Raw Codegen output
+│   ├── playwright-test-feature.js     # Experimental tests
+│   └── ...                            # Auto-cleaned during development
+├── tests/                              # Production tests only
+│   ├── 01_Module/
+│   │   ├── 01_01_01_TestName.spec.ts
+│   │   └── 01_01_02_AnotherTest.spec.ts
+│   └── ...
+```
+
+**Purpose of `tmp/` directory**:
+- Isolate experimental/recorded tests from production
+- Easy cleanup of temporary files
+- Clear project structure
+- Gitignored - won't pollute version control
+- Safe testing ground before creating production tests
+
+**Workflow**:
+1. **Record** -> Save to `{{PLAYWRIGHT_DIR}}/tmp/playwright-test-*.js`
+2. **Test & Iterate** -> Run and refine in `tmp/`
+3. **Convert** -> Extract POMs, refactor, add structure
+4. **Move** -> Create production test in `tests/NN_Module/NN_NN_NN_Name.spec.ts`
+5. **Clean** -> Delete `tmp/` files after conversion
+
+### Basic Recording
+
+```bash
+cd {{PLAYWRIGHT_DIR}}
+
+# Start recording on test environment
+npx playwright codegen {{BASE_URL}}/login
+
+# Record with specific browser
+npx playwright codegen --browser=chromium {{BASE_URL}}
+
+# Record with device emulation
+npx playwright codegen --device="iPhone 12" {{BASE_URL}}
+
+# Record with existing context (logged in state)
+npx playwright codegen --load-storage=auth.json {{BASE_URL}}
+```
+
+### Recording Workflow
+
+**Recommended Process**: Record -> Save to `tmp/` -> Test -> Convert -> Production
+
+**Step 1: Configuration Files**
+
+The project uses configuration files for environment settings and credentials:
+
+- **`.env`** - Environment configuration (`{{PLAYWRIGHT_DIR}}/.env`)
+  - `BASE_URL` - Application base URL (default: `{{BASE_URL}}`)
+  - `COMPANY_NAME` - Company/tenant to test
+  - `BROWSER`, `HEADLESS`, `WORKERS` - Test execution settings
+
+- **`{{CREDENTIALS_FILE}}`** - Secure credentials (`{{PLAYWRIGHT_DIR}}/{{CREDENTIALS_FILE}}`)
+  - Contains login credentials for different environments/tenants
+  - **NOT in git** - stored locally only
+  - Structure: `{ "tenantName": { "email": { "right": "...", "wrong": "..." }, "password": {...} } }`
+
+- **`playwright.config.ts`** - Main Playwright configuration
+  - Loads environment variables from `.env`
+  - Configures browsers, reporters, timeouts
+  - Sets base URL, locale, timezone
+
+**Example credentials usage**:
+```typescript
+// {{CREDENTIALS_FILE}} structure
+{
+  "{{TENANT_NAME}}": {
+    "email": { "right": "user@test.example.com", "wrong": "wrong@wrong.com" },
+    "password": { "right": "SecurePassword!", "wrong": "WrongPass" }
+  }
+}
+```
+
+**Step 2: Prepare tmp/ Directory**
+
+The `tmp/` directory is **already created and configured** in the project:
+- Directory exists at `{{PLAYWRIGHT_DIR}}/tmp/`
+- Already in `.gitignore` (no need to add manually)
+- Ready for storing temporary recorded tests
+
+**No need to run mkdir commands** - the directory structure is already set up!
+
+**Step 3: Auto-Detect Dev Server (Optional for local testing)**
+
+If testing locally, detect running dev servers:
+
+```bash
+# Check for running dev servers on common ports
+lsof -i :3000 -i :3001 -i :5173 -i :8080 | grep LISTEN
+
+# Or manually check your dev server
+npm run dev  # Should show: Local: http://localhost:XXXX
+```
+
+**Common dev server ports**:
+- Vite: `5173`
+- Vue CLI: `8080`
+- Next.js: `3000`
+- Custom: check your project configuration
+
+**Step 4: Start Codegen**
+```bash
+cd {{PLAYWRIGHT_DIR}}
+
+# Use BASE_URL from .env (test environment)
+npx playwright codegen {{BASE_URL}}/login
+
+# Or specify output file for tmp/ directory
+npx playwright codegen --output={{PLAYWRIGHT_DIR}}/tmp/playwright-test-[feature].js {{BASE_URL}}/login
+
+# Or for local development
+npx playwright codegen http://localhost/login
+```
+
+**Step 5: Interact with Application**
+- Click through the user flow you want to test
+- Fill forms
+- Navigate pages
+- Trigger modals/dropdowns
+- Complete the scenario
+
+**Step 6: Save to tmp/ Directory**
+- Codegen window shows generated code in real-time
+- Copy the code when scenario is complete
+- Save as `{{PLAYWRIGHT_DIR}}/tmp/playwright-test-[feature].js`
+- Example: `{{PLAYWRIGHT_DIR}}/tmp/playwright-test-login-flow.js`
+
+**Step 7: Test & Iterate in tmp/**
+```bash
+cd {{PLAYWRIGHT_DIR}}
+
+# Run the temporary test
+npx playwright test tmp/playwright-test-login-flow.js --headed
+
+# Refine and re-record if needed
+```
+
+
+## Recording Complex Flows
+
+### Multi-Step Scenarios
+
+**Scenario**: Record user performing a multi-step workflow
+
+```bash
+# Start recording
+npx playwright codegen {{BASE_URL}}/login
+
+# Perform actions:
+# 1. Login
+# 2. Navigate to target module
+# 3. Click "Add" button
+# 4. Fill the form
+# 5. Submit
+# 6. Verify item created
+```
+
+**Recorded Output**:
+```typescript
+test('test', async ({ page }) => {
+  await page.goto('{{BASE_URL}}/login');
+  await page.getByPlaceholder('Email').fill('test@example.com');
+  await page.getByRole('button', { name: 'Login' }).click();
+  await page.getByRole('link', { name: 'Target Module' }).click();
+  await page.getByRole('button', { name: 'Add item' }).click();
+  await page.getByPlaceholder('Item title').fill('New item');
+  await page.getByRole('button', { name: 'Save' }).click();
+  await expect(page.getByText('Item created')).toBeVisible();
+});
+```
+### Recording Modal Interactions
+
+**Challenge**: Modals, dropdowns, dynamic content
+
+```bash
+# Record with slower actions to see dynamic content
+npx playwright codegen --slowMo=500 {{BASE_URL}}
+```
+
+**Recorded**:
+```typescript
+await page.getByRole('button', { name: 'Add' }).click();
+await page.locator('#modal').getByPlaceholder('Name').fill('Test');
+await page.getByRole('button', { name: 'Save' }).click();
+```
+
+## Recording Authentication Flows
+
+### Save Authentication State
+
+```bash
+# Login and save state
+npx playwright codegen --save-storage=auth.json {{BASE_URL}}/login
+
+# Use saved state for recording other flows
+npx playwright codegen --load-storage=auth.json {{BASE_URL}}/dashboard
+```
+
+**Benefits**:
+- Skip login for every recording
+- Focus on specific features
+- Faster recording workflow
+
+## Best Practices for Recording
+
+### 1. Prepare Before Recording
+
+- Know the user flow you want to test
+- Have test data ready (if needed)
+- Clear browser storage before starting
+- Use test environment
+
+### 2. During Recording
+
+- **Go slow** - Give Codegen time to capture actions
+- **Use slowMo** - `--slowMo=500` for complex interactions
+- **Wait for elements** - Let pages fully load
+- **Avoid unnecessary clicks** - Stay focused on test scenario
+
+### 3. After Recording
+
+- **Don't commit raw Codegen output**
+- **Extract Page Objects immediately**
+- **Replace all selectors with data-testid**
+- **Add proper test structure**
+- **Use dynamic test data**
+
+### 4. Recording Checklist
+
+### Before moving from tmp/ to production:
+
+- [ ] Tested in `tmp/` directory first
+- [ ] Replaced selectors with data-testid
+- [ ] Verified test runs successfully
+
+## Common Recording Scenarios
+
+### Scenario 1: Login Flow
+
+**Record**:
+```bash
+npx playwright codegen {{BASE_URL}}/login
+# Interact: Fill email -> Click continue -> Fill password -> Submit
+```
+
+## Troubleshooting Recording
+
+### Issue: Codegen doesn't capture action
+
+**Solution**:
+- Use `--slowMo=1000` for slower execution
+- Wait for elements to be fully visible
+- Try clicking the element multiple times
+
+### Issue: Generated selectors are fragile
+
+**Solution**:
+- Add data-testid to application components
+- Use selector fallbacks in POMs
+- Prefer stable attributes
+
+### Issue: Recording includes unnecessary steps
+
+**Solution**:
+- Clear recording and start fresh
+- Focus on main flow only
+- Remove debugging clicks from recording
+
+### Issue: Authentication state not saved
+
+**Solution**:
+```bash
+# Ensure you complete login before saving
+npx playwright codegen --save-storage=auth.json {{BASE_URL}}/login
+
+# Verify auth.json file created
+ls -la auth.json
+
+# Load in next recording
+npx playwright codegen --load-storage=auth.json {{BASE_URL}}
+```
+
+## Quick Reference
+
+### tmp/ Workflow
+
+The `tmp/` directory is **already set up** in the project - no need to create it.
+
+```bash
+# 1. Navigate to playwright directory
+cd {{PLAYWRIGHT_DIR}}
+
+# 2. Record test
+npx playwright codegen {{BASE_URL}}/login
+# Save output to: {{PLAYWRIGHT_DIR}}/tmp/playwright-test-login.js
+
+# 3. Test in tmp/
+npx playwright test tmp/playwright-test-login.js --headed
+
+# 4. Refine if needed
+npx playwright codegen {{BASE_URL}}/login
+# Update {{PLAYWRIGHT_DIR}}/tmp/playwright-test-login.js
+
+# 5. Convert to production
+# Create: tests/01_Module/01_01_01_TestName.spec.ts
+# Following POM patterns from main playwright skill
+
+# 6. Clean up
+rm {{PLAYWRIGHT_DIR}}/tmp/playwright-test-login.js
+```
+
+### Auto-Detect Dev Servers
+
+```bash
+# Check for running servers
+lsof -i :3000 -i :3001 -i :5173 -i :8080 | grep LISTEN
+
+# Or check npm process
+ps aux | grep "npm run dev"
+
+# Start your dev server
+npm run dev  # Note the port shown
+```
+
+### Recording Commands
+
+**IMPORTANT**: URL is **required** before running any Codegen command. If user doesn't provide URL, ask them for it first.
+
+```bash
+# Basic recording
+npx playwright codegen <URL>
+
+# Specific browser
+npx playwright codegen --browser=firefox <URL>
+
+# Device emulation
+npx playwright codegen --device="iPhone 12" <URL>
+
+# Slow motion
+npx playwright codegen --slowMo=500 <URL>
+
+# Save auth state
+npx playwright codegen --save-storage=auth.json <URL>
+
+# Load auth state
+npx playwright codegen --load-storage=auth.json <URL>
+
+# With viewport size
+npx playwright codegen --viewport-size=1920,1080 <URL>
+
+# Specific language
+npx playwright codegen --lang=en <URL>
+```
+
+## Resources
+
+- **Main Playwright Skill**: `.github/skills/playwright/SKILL.md`
+- **Code Review Skill**: `.github/skills/playwright-codereview/SKILL.md`
+- **Playwright Codegen Docs**: https://playwright.dev/docs/codegen
+- **Project README**: `{{PLAYWRIGHT_DIR}}/README.md`
+
+---
+
+**Remember**: Codegen is a starting point, not the final product. Always convert recorded tests to follow project conventions.

package/templates/packs/playwright/_guidelines.md

@@ -0,0 +1,12 @@
+
+
+---
+
+## Playwright E2E
+
+- Test directory: `{{PLAYWRIGHT_DIR}}`
+- Base URL: `{{BASE_URL}}`
+- Use Page Object Model pattern
+- Use `data-testid` selectors, avoid CSS/XPath
+- Always wait for elements before interacting
+- See `.ai/skills/playwright/` for writing and recording tests

package/templates/packs/playwright/pack.json

@@ -0,0 +1,9 @@
+{
+  "name": "Playwright E2E",
+  "description": "Testy end-to-end z Page Object Model",
+  "default": false,
+  "placeholders": {
+    "PLAYWRIGHT_DIR": { "question": "Katalog testow Playwright", "default": "tests/e2e" },
+    "BASE_URL": { "question": "Base URL aplikacji", "default": "http://localhost:3000" }
+  }
+}