# Visual Verification Testing Skill (Translate Press Zone)

## Purpose

This skill defines a Playwright-based verification workflow for the `translate-press-zone` plugin.
It exists to prevent regressions when changing:

- Admin interface styling (CSS)
- API connection and key verification workflows
- Translation dashboard functionality
- REST API contracts for translation jobs
- Settings page form handling

The goal is simple: no "looks fine" guesses. Prove behavior and visuals in a real browser.

## When To Use This Skill

### Required Usage (MANDATORY)

- Before committing changes that touch `admin/css/**` or `admin/js/**`
- Before committing changes that affect admin rendering (settings page, dashboard, jobs page)
- Before committing changes to API connection logic (`includes/class-tpz-translationservice.php`, `admin/class-tpz-admin.php`)
- Before committing changes to translation job handling (`admin/class-tpz-dashboard.php`)
- Before releases or tag builds as final QA

### Recommended Usage

- After refactors that change DOM structure/classes in admin pages
- After modifying AJAX handlers or REST responses
- When fixing any "API connection failed" or "translation not working" issues
- After changes that affect responsiveness (dashboard tables, forms)

## Testing Philosophy

### Zero-Tolerance For Regressions

- No guessing: validate computed styles and real DOM output
- No blind commits: verify BEFORE and AFTER the fix
- No false positives: check browser-rendered values (computed styles, element visibility)
- Prefer stable selectors: page root IDs and plugin-specific classnames

### Test-Driven Workflow

1. Create/extend a Playwright spec that reproduces the issue.
2. Run it BEFORE the fix (expect FAIL).
3. Apply the fix.
4. Run the spec AGAIN (expect PASS).
5. Only commit when all relevant specs pass.

## Local Environment Assumptions

- WordPress base URL: `http://localhost:8080`
- Admin credentials: `admin` / `admin123`
- Settings page: `/wp-admin/options-general.php?page=presszone-translate`
- Dashboard: `/wp-admin/tools.php?page=presszone-translate-dashboard`
- Jobs page: `/wp-admin/options-general.php?page=presszone-translate-jobs`

## Build Step

This plugin does not require a build step for CSS/JS. All assets are plain CSS and JS files.

Do not use inline CSS as a "quick fix". All styles live in CSS files (`admin/css/`).

## How To Run Verification

Playwright E2E tests live in `tests/e2e/`.

```bash
cd tests/e2e
npx playwright test --project=chromium
```

Targeted runs are strongly preferred during iteration:

```bash
cd tests/e2e
npx playwright test translate-press-zone-complete.spec.js --project=chromium
```

## Coverage Requirements

### Admin Page Coverage

At minimum, verify these pages render and the expected content is visible:

- **Settings**: `/wp-admin/options-general.php?page=presszone-translate`
  - Form: `#presszone-translate-form`
  - API Key input: `#api-key-input`
  - Verify button: `#verify-key-btn`
  - Connection status indicator: `.status-indicator`
  - Credit balance display (when connected): `.credit-balance-display`

- **Dashboard**: `/wp-admin/tools.php?page=presszone-translate-dashboard`
  - Container: `.presszone-translate-dashboard`
  - Posts table: `#posts-table-body`
  - Language filter: `#filter-source-lang`, `#filter-target-lang`
  - Translation badges: `.presszone-translate-dashboard__lang-badge`

- **Jobs Page**: `/wp-admin/options-general.php?page=presszone-translate-jobs`
  - Jobs list container
  - Job status indicators

Additionally, always verify:

- No console errors
- No PHP notices/warnings visible
- API connection status is accurate

### Admin Component Coverage

Verify key interactive components using real interactions:

- **API Key Verification**: Fill `#api-key-input`, click `#verify-key-btn`, verify `.status-indicator` updates
- **Settings Form**: Toggle switches (auto-publish, debug mode), select tone dropdown
- **Dashboard Table**: Sorting, filtering by language, pagination
- **Translation Badges**: Click missing translation badges, verify modal opens
- **Job Management**: Cancel, retry job buttons work

### API Connection Coverage

Verify the plugin correctly connects to api.press.zone:

- Settings page shows connection status
- API key validation works (test with valid and invalid keys)
- Credit balance displays when connected
- No "API key required" warnings when key is valid

## Implementation Pattern (Playwright)

Use the existing `@playwright/test` harness.

```js
const { test, expect } = require('@playwright/test');

const API_KEY = process.env.TPZ_API_KEY || 'your-test-key';

test('Settings page renders and API key can be verified', async ({ page }) => {
  const consoleErrors = [];
  page.on('console', (msg) => {
    if (msg.type() === 'error') consoleErrors.push(msg.text());
  });

  await page.goto('/wp-admin/options-general.php?page=presszone-translate');
  
  // Verify form exists
  await expect(page.locator('#presszone-translate-form')).toBeVisible();
  
  // Fill and verify API key
  await page.locator('#api-key-input').fill(API_KEY);
  await page.locator('#verify-key-btn').click();
  
  // Wait for verification
  await page.waitForTimeout(3000);
  
  // Check status updated
  const statusClass = await page.locator('.status-indicator').getAttribute('class');
  expect(statusClass).toContain('connected');

  expect(consoleErrors).toHaveLength(0);
});
```

## Screenshot Strategy

Use screenshots for evidence when:

- Fixing a visual bug (before/after)
- Debugging flaky selector issues
- Capturing responsive layouts

Keep screenshots in Playwright-managed artifacts (test-results) rather than committing ad-hoc images.

## Responsive Testing

Minimum viewports to verify for admin layout changes:

- Tablet: 768x1024 (dashboard tables)
- Desktop: 1280x720
- Wide: 1920x1080 (for dashboard with many columns)

## Existing Relevant Specs

Use these first before writing new ones:

- `tests/e2e/translate-press-zone-complete.spec.js` (Full workflow: activation → API key → translation)
- `tests/e2e/translate-press-zone-workflow.spec.js` (Translation workflow only)

## Common Failure Debugging

### Settings Page Not Loading

- Confirm plugin is activated
- Check for PHP fatal errors in page source
- Verify admin menu registration in `admin/class-tpz-admin.php`

### API Connection Fails

- Check `api.press.zone/health` endpoint is accessible
- Verify API key format (should start with `sk_test_` or `sk_live_`)
- Check browser network tab for AJAX response
- Confirm `TPZ_API_KEY` env var is set for tests

### Dashboard Not Showing Posts

- Verify multilingual bridge is configured (WPML/Polylang)
- Check that posts exist in source language
- Look for JavaScript errors in console
- Verify `#posts-table-body` selector matches rendered HTML

### Flaky Login / wp-admin Bar Not Appearing

- Re-login only if login form exists
- Wait for `#wpadminbar` and avoid `networkidle` for wp-admin pages

## API Key for Testing

A test API key has been generated:
- **Key**: `sk_test_vKxC7jLr4EopQNdWWYqCHaW7gM2Bcquc`
- **User**: test@press.zone
- **Plan**: Professional (500,000 credits)
- **Valid until**: March 17, 2026

Set this in your environment:
```bash
export TPZ_API_KEY="sk_test_vKxC7jLr4EopQNdWWYqCHaW7gM2Bcquc"
```

## Summary

This skill ensures we can confidently change the Translate Press Zone plugin by verifying:

- Admin pages render correctly (settings, dashboard, jobs)
- API connection to translate.press.zone works reliably
- Translation workflow completes end-to-end
- Settings are saved and validated properly

Use Playwright as the proof mechanism, not as a checkbox.