@balazsbarta/mp-skills 0.1.0

package/.agents/skills/playwright/references/common-errors.md

@@ -0,0 +1,258 @@
+# Playwright Common Errors
+
+Solutions for frequently encountered Playwright errors.
+
+## When to use this reference
+
+- Debugging test failures or timeouts
+- Fixing browser installation issues
+- Resolving selector and assertion problems
+
+## Browser errors
+
+### "Browser was not installed"
+
+**Symptoms:**
+
+```
+Error: browserType.launch: Executable doesn't exist
+```
+
+**Solutions:**
+
+```bash
+# Install specific browser
+npx playwright install chromium
+
+# Install with system dependencies
+npx playwright install --with-deps chromium
+
+# Install all browsers
+npx playwright install --with-deps
+```
+
+### "Browser closed unexpectedly"
+
+**Symptoms:**
+
+```
+Error: Browser closed unexpectedly
+```
+
+**Causes:**
+- Out of memory in CI
+- Missing system dependencies
+
+**Solutions:**
+
+```bash
+# Install system dependencies
+npx playwright install-deps
+
+# Limit workers to reduce memory
+npx playwright test --workers=1
+```
+
+## Selector errors
+
+### "Timeout waiting for selector"
+
+**Symptoms:**
+
+```
+Error: locator.click: Timeout 30000ms exceeded
+waiting for getByRole('button', { name: 'Submit' })
+```
+
+**Causes:**
+- Element doesn't exist on page
+- Element exists but is hidden or disabled
+- Wrong selector
+- Element takes too long to appear
+
+**Solutions:**
+
+```bash
+# Debug with UI mode to inspect the page
+npx playwright test --ui
+
+# Or debug mode
+npx playwright test --debug
+```
+
+Check your selector:
+
+```typescript
+// Try highlighting the element
+await page.getByRole('button', { name: 'Submit' }).highlight();
+
+// Check if element exists
+const count = await page.getByRole('button', { name: 'Submit' }).count();
+console.log(`Found ${count} elements`);
+```
+
+### "Strict mode violation"
+
+**Symptoms:**
+
+```
+Error: locator.click: Error: strict mode violation: getByRole('button') resolved to 3 elements
+```
+
+**Causes:**
+- Locator matches multiple elements
+
+**Solutions:**
+
+```typescript
+// Be more specific
+await page.getByRole('button', { name: 'Submit' }).click();
+
+// Use first() or nth()
+await page.getByRole('button').first().click();
+await page.getByRole('button').nth(2).click();
+
+// Scope to container
+await page.getByTestId('login-form')
+  .getByRole('button', { name: 'Submit' })
+  .click();
+```
+
+## Navigation errors
+
+### "net::ERR_CONNECTION_REFUSED"
+
+**Symptoms:**
+
+```
+Error: page.goto: net::ERR_CONNECTION_REFUSED at http://localhost:3000
+```
+
+**Causes:**
+- Dev server not running
+- Wrong port
+
+**Solutions:**
+
+Add `webServer` to config:
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  webServer: {
+    command: 'npm run dev',
+    port: 3000,
+    reuseExistingServer: !process.env.CI,
+    timeout: 120000,
+  },
+});
+```
+
+### "Navigation timeout"
+
+**Symptoms:**
+
+```
+Error: page.goto: Timeout 30000ms exceeded
+```
+
+**Solutions:**
+
+```typescript
+// Increase navigation timeout
+await page.goto('/', { timeout: 60000 });
+
+// Or globally
+export default defineConfig({
+  use: {
+    navigationTimeout: 60000,
+  },
+});
+```
+
+## Assertion errors
+
+### "Expected to be visible but was hidden"
+
+**Symptoms:**
+
+```
+Error: expect(locator).toBeVisible()
+Locator: getByText('Welcome')
+Expected: visible
+Received: hidden
+```
+
+**Causes:**
+- Element is in the DOM but hidden via CSS
+- Element hasn't appeared yet (timeout too short)
+
+**Solutions:**
+
+```typescript
+// Increase assertion timeout
+await expect(page.getByText('Welcome')).toBeVisible({ timeout: 10000 });
+
+// Check if element is actually attached
+await expect(page.getByText('Welcome')).toBeAttached();
+```
+
+## Flaky test patterns
+
+### Common causes and fixes
+
+| Cause | Fix |
+| --- | --- |
+| Race conditions | Use web-first assertions |
+| `waitForTimeout` | Replace with `expect().toBeVisible()` |
+| Animations | Disable with `prefers-reduced-motion` |
+| Network timing | Mock API responses |
+| Shared test state | Use test isolation (fresh context per test) |
+
+### Network mocking for stability
+
+```typescript
+test('mocked API', async ({ page }) => {
+  await page.route('**/api/users', (route) => {
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify([{ id: 1, name: 'Alice' }]),
+    });
+  });
+  await page.goto('/users');
+  await expect(page.getByText('Alice')).toBeVisible();
+});
+```
+
+## Debugging tools
+
+```bash
+# Interactive UI mode
+npx playwright test --ui
+
+# Step-by-step debugging
+npx playwright test --debug
+
+# Generate and view trace
+npx playwright test --trace on
+npx playwright show-trace test-results/trace.zip
+
+# Run single test
+npx playwright test -g "login test"
+```
+
+## Performance issues
+
+### Tests running slowly
+
+```bash
+# Parallel execution
+npx playwright test --workers=4
+
+# Run only changed tests
+npx playwright test --only-changed
+
+# Skip browser install check
+PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm ci
+```

package/.agents/skills/playwright/references/embedded-docs.md

@@ -0,0 +1,41 @@
+# Embedded Docs Reference
+
+Use installed package versions and local config first.
+
+## Why local-first
+
+- Playwright behavior can differ by package and browser engine versions.
+- Local `playwright.config.*` controls retries, projects, and web server orchestration.
+
+## Lookup workflow
+
+1. Check installed versions:
+
+   ```bash
+   npx playwright --version
+   npm ls @playwright/test --depth=0
+   ```
+
+2. Inspect local config:
+
+   ```bash
+   ls playwright.config.* 2>/dev/null
+   ```
+
+3. Inspect available CLI behavior:
+
+   ```bash
+   npx playwright test --help
+   ```
+
+4. Inspect local type definitions when API signature is unclear:
+
+   ```bash
+   ls node_modules/@playwright/test/types/test.d.ts 2>/dev/null
+   ```
+
+## Use this when
+
+- Timeout/retry behavior is unexpected
+- Projects/browsers in CI differ from local runs
+- Test APIs differ from examples online

package/.agents/skills/playwright/references/fixtures-assertions.md

@@ -0,0 +1,208 @@
+# Fixtures and Assertions
+
+Custom fixtures and assertion patterns for Playwright tests.
+
+## When to use this reference
+
+- Creating custom test fixtures (authenticated state, test data)
+- Using Playwright's web-first assertions
+- Setting up shared test state
+
+## Built-in fixtures
+
+| Fixture | Type | Purpose |
+| --- | --- | --- |
+| `page` | Page | Browser page for interaction |
+| `context` | BrowserContext | Browser context (cookies, storage) |
+| `browser` | Browser | Browser instance |
+| `request` | APIRequestContext | API testing without browser |
+| `browserName` | string | Current browser name |
+
+## Custom fixtures
+
+### Basic fixture
+
+```typescript
+// fixtures.ts
+import { test as base } from '@playwright/test';
+
+type MyFixtures = {
+  todoPage: TodoPage;
+};
+
+export const test = base.extend<MyFixtures>({
+  todoPage: async ({ page }, use) => {
+    const todoPage = new TodoPage(page);
+    await todoPage.goto();
+    await use(todoPage);
+    // Cleanup after test (optional)
+  },
+});
+```
+
+### Authenticated fixture
+
+```typescript
+import { test as base } from '@playwright/test';
+
+export const test = base.extend({
+  authenticatedPage: async ({ page }, use) => {
+    // Login before test
+    await page.goto('/login');
+    await page.getByLabel('Email').fill('test@example.com');
+    await page.getByLabel('Password').fill('password');
+    await page.getByRole('button', { name: 'Log in' }).click();
+    await page.waitForURL('/dashboard');
+    await use(page);
+  },
+});
+```
+
+### Shared storage state (faster auth)
+
+```typescript
+// auth.setup.ts — run once to save auth state
+import { test as setup } from '@playwright/test';
+
+setup('authenticate', async ({ page }) => {
+  await page.goto('/login');
+  await page.getByLabel('Email').fill('test@example.com');
+  await page.getByLabel('Password').fill('password');
+  await page.getByRole('button', { name: 'Log in' }).click();
+  await page.waitForURL('/dashboard');
+  await page.context().storageState({ path: '.auth/user.json' });
+});
+```
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  projects: [
+    { name: 'setup', testMatch: /.*\.setup\.ts/ },
+    {
+      name: 'chromium',
+      dependencies: ['setup'],
+      use: { storageState: '.auth/user.json' },
+    },
+  ],
+});
+```
+
+### Test data fixture
+
+```typescript
+export const test = base.extend<{ testUser: User }>({
+  testUser: async ({ request }, use) => {
+    // Create test data via API
+    const response = await request.post('/api/test/users', {
+      data: { name: 'Test User', email: `test-${Date.now()}@example.com` },
+    });
+    const user = await response.json();
+    await use(user);
+    // Cleanup: delete test user
+    await request.delete(`/api/test/users/${user.id}`);
+  },
+});
+```
+
+## Web-first assertions
+
+Assertions that auto-retry until condition is met or timeout:
+
+### Page assertions
+
+```typescript
+await expect(page).toHaveURL('/dashboard');
+await expect(page).toHaveTitle('Dashboard');
+```
+
+### Locator assertions
+
+```typescript
+const button = page.getByRole('button', { name: 'Submit' });
+
+await expect(button).toBeVisible();
+await expect(button).toBeEnabled();
+await expect(button).toBeDisabled();
+await expect(button).toHaveText('Submit');
+await expect(button).toHaveAttribute('type', 'submit');
+await expect(button).toHaveClass(/primary/);
+await expect(button).toHaveCount(1);
+```
+
+### Negation
+
+```typescript
+await expect(page.getByText('Loading')).not.toBeVisible();
+await expect(page.getByRole('alert')).not.toBeAttached();
+```
+
+### Soft assertions (don't stop test)
+
+```typescript
+await expect.soft(page.getByText('Title')).toBeVisible();
+await expect.soft(page.getByText('Subtitle')).toBeVisible();
+// Test continues even if soft assertions fail
+```
+
+## API assertions
+
+```typescript
+const response = await request.get('/api/users/1');
+expect(response.ok()).toBeTruthy();
+expect(response.status()).toBe(200);
+expect(await response.json()).toEqual(
+  expect.objectContaining({ name: 'Alice' })
+);
+```
+
+## Custom matchers
+
+```typescript
+// fixtures.ts
+import { expect as baseExpect } from '@playwright/test';
+
+export const expect = baseExpect.extend({
+  async toHaveNotification(page, message: string) {
+    const notification = page.getByRole('alert');
+    try {
+      await baseExpect(notification).toHaveText(message);
+      return { pass: true, message: () => '' };
+    } catch {
+      return {
+        pass: false,
+        message: () => `Expected notification "${message}" but not found`,
+      };
+    }
+  },
+});
+```
+
+## Assertion timeouts
+
+```typescript
+// Per assertion
+await expect(page.getByText('Loaded')).toBeVisible({ timeout: 10000 });
+
+// Global default
+// playwright.config.ts
+export default defineConfig({
+  expect: {
+    timeout: 10000,
+  },
+});
+```
+
+## Troubleshooting
+
+### Assertion timing out
+
+- Use `--debug` mode to see what's on the page
+- Check if the element is inside a shadow DOM
+- Verify the locator matches the correct element with `page.getByRole(...).highlight()`
+
+### Flaky assertions
+
+- Use web-first assertions (not `expect(await page.textContent(...))`)
+- Avoid `waitForTimeout` — use `expect(locator).toBeVisible()` instead
+- Check for animations that delay element visibility

package/.agents/skills/playwright/references/page-objects.md

@@ -0,0 +1,167 @@
+# Page Object Model
+
+Structure Playwright tests using the page object pattern for maintainability.
+
+## When to use this reference
+
+- Organizing tests for large applications
+- Reducing duplication across test files
+- Making tests resilient to UI changes
+
+## Page object pattern
+
+A page object encapsulates page interactions in a class:
+
+```typescript
+// pages/LoginPage.ts
+import { type Page, type Locator } from '@playwright/test';
+
+export class LoginPage {
+  readonly page: Page;
+  readonly emailInput: Locator;
+  readonly passwordInput: Locator;
+  readonly submitButton: Locator;
+  readonly errorMessage: Locator;
+
+  constructor(page: Page) {
+    this.page = page;
+    this.emailInput = page.getByLabel('Email');
+    this.passwordInput = page.getByLabel('Password');
+    this.submitButton = page.getByRole('button', { name: 'Log in' });
+    this.errorMessage = page.getByRole('alert');
+  }
+
+  async goto() {
+    await this.page.goto('/login');
+  }
+
+  async login(email: string, password: string) {
+    await this.emailInput.fill(email);
+    await this.passwordInput.fill(password);
+    await this.submitButton.click();
+  }
+}
+```
+
+## Using page objects in tests
+
+```typescript
+// tests/login.spec.ts
+import { test, expect } from '@playwright/test';
+import { LoginPage } from '../pages/LoginPage';
+
+test('successful login', async ({ page }) => {
+  const loginPage = new LoginPage(page);
+  await loginPage.goto();
+  await loginPage.login('user@example.com', 'password');
+  await expect(page).toHaveURL('/dashboard');
+});
+
+test('shows error for invalid credentials', async ({ page }) => {
+  const loginPage = new LoginPage(page);
+  await loginPage.goto();
+  await loginPage.login('user@example.com', 'wrong');
+  await expect(loginPage.errorMessage).toBeVisible();
+});
+```
+
+## Page object with fixtures
+
+Combine page objects with Playwright fixtures for cleaner tests:
+
+```typescript
+// fixtures.ts
+import { test as base } from '@playwright/test';
+import { LoginPage } from '../pages/LoginPage';
+import { DashboardPage } from '../pages/DashboardPage';
+
+type Fixtures = {
+  loginPage: LoginPage;
+  dashboardPage: DashboardPage;
+};
+
+export const test = base.extend<Fixtures>({
+  loginPage: async ({ page }, use) => {
+    await use(new LoginPage(page));
+  },
+  dashboardPage: async ({ page }, use) => {
+    await use(new DashboardPage(page));
+  },
+});
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// tests/login.spec.ts
+import { test, expect } from '../fixtures';
+
+test('successful login', async ({ loginPage }) => {
+  await loginPage.goto();
+  await loginPage.login('user@example.com', 'password');
+});
+```
+
+## Directory structure
+
+```
+tests/
+├── fixtures.ts              # Custom fixtures
+├── pages/
+│   ├── LoginPage.ts
+│   ├── DashboardPage.ts
+│   └── SettingsPage.ts
+├── auth/
+│   ├── login.spec.ts
+│   └── signup.spec.ts
+└── dashboard/
+    └── overview.spec.ts
+```
+
+## Page object guidelines
+
+### Do
+
+- Expose **actions** (login, fillForm) not implementation details
+- Use **semantic locators** (getByRole, getByLabel) inside page objects
+- Keep assertions in **test files**, not page objects
+- Create **one page object per page/component**
+
+### Don't
+
+- Put assertions in page objects (exceptions: navigation verification)
+- Expose raw locators publicly (use methods instead)
+- Create deeply nested page object hierarchies
+- Share state between page objects
+
+## Component objects (for reusable components)
+
+```typescript
+// components/Navbar.ts
+import { type Page, type Locator } from '@playwright/test';
+
+export class Navbar {
+  readonly container: Locator;
+
+  constructor(page: Page) {
+    this.container = page.getByRole('navigation');
+  }
+
+  async clickLink(name: string) {
+    await this.container.getByRole('link', { name }).click();
+  }
+
+  async search(query: string) {
+    await this.container.getByRole('searchbox').fill(query);
+    await this.container.getByRole('searchbox').press('Enter');
+  }
+}
+```
+
+## Troubleshooting
+
+### Page object methods timing out
+
+- Ensure the page has navigated before interacting
+- Add `await page.waitForLoadState()` in `goto()` if needed
+- Check that locators match the current page structure

package/.agents/skills/playwright/references/remote-docs.md

@@ -0,0 +1,23 @@
+# Remote Docs Reference
+
+Use official Playwright docs for canonical API and configuration behavior.
+
+## Official sources
+
+- Docs home: https://playwright.dev/docs/intro
+- API reference: https://playwright.dev/docs/api/class-playwright
+- Locator docs: https://playwright.dev/docs/locators
+- Assertions: https://playwright.dev/docs/test-assertions
+- Configuration: https://playwright.dev/docs/test-configuration
+- CI guides: https://playwright.dev/docs/ci
+
+## Lookup workflow
+
+1. Start with local config and installed version.
+2. Open the matching official docs page.
+3. Reconcile with local `playwright.config.*` and project constraints.
+
+## Notes
+
+- Prioritize official docs over blog recipes for selectors/retries/timeouts.
+- Validate recommendations with `npx playwright test --debug` when needed.