# AGENTS.md

## Purpose
This agent is used for **website QA/testing** of real pages in a browser environment.

The testing must be performed with **Playwright**.
Visual page inspection must be performed with the **playwright-screenshot-inspector** skill.
The agent must check the **real rendered page**, not just raw HTML.

---

## Required tools and skills
- **Playwright** — for browser automation, page opening, interaction, form submission, and response inspection.
- **playwright-screenshot-inspector** — for screenshot-based visual inspection of the rendered page.

---

## General testing rules
1. Always test the **real live page URL** provided by the user.
2. Always test both:
   - **Desktop / PC viewport**
   - **Mobile viewport**
3. Always capture screenshots for both desktop and mobile.
4. Compare the actual rendered page against the screen/reference provided by the user.
5. **All interactive UI elements must be tested manually via interaction.**
6. Report all findings clearly and classify issues by severity:
   - **Critical**
   - **Major**
   - **Minor**
7. Do not stop after the first issue. Complete the full checklist.
8. At the end of testing, create a **summary HTML file** with all findings.
9. All results and summaries sould be in Russian language.
10. Split form submission for 2 parts 
First is forms submition summary results and accessability in table form
Second is details in hidden layout 

### Configuration-driven page selection
- Use `pages.json` in the workspace root as the default source of primary pages and visual references.
- If the user asks to **just check the site** without specifying a single page, run the full list from `pages.json`.
- If the user provides a **specific page URL**, first prepare to test that exact URL.
- In that case, ask one short question: whether to also test the primary pages from `pages.json`.
- If the user answers **yes**, test:
  - the explicit URL from the user request
  - the pages from `pages.json`
- Deduplicate identical URLs before running checks.
- If the user answers **no**, test only the explicit URL from the request.
- For visual comparison, use the reference data from `pages.json` when present:
  - `desktop_screenshot`
  - `mobile_screenshot`
  - `figma_url`
- If a page in `pages.json` has no reference assets yet, still test the real page and clearly note that visual comparison is limited by missing reference materials.

---

## Required order of checks

### 1. Visual page and UI interaction check
The user will provide:
- a page URL
- a reference screen/mockup/screenshot

#### 1.1 Open and inspect the real page
- Open the provided page in Playwright.
- Wait until the page is fully loaded and visually stable.
- Test in:
  - Desktop viewport
  - Mobile viewport

#### 1.2 Capture screenshots
- Take full-page screenshots for both desktop and mobile.
- Use **playwright-screenshot-inspector** to inspect the screenshots.

#### 1.3 Compare with the provided reference
Check for differences between:
- the real page
- the provided screen/reference

Look for:
- incorrect layout structure
- broken blocks
- missing elements
- different text/content placement
- wrong fonts, sizes, spacing, alignment
- overlap or clipping
- responsive/mobile issues
- hidden or misplaced elements

---

### 1.4 UI interaction testing (MANDATORY)
If any interactive UI elements are present, they **must be tested**.

This includes (but is not limited to):
- buttons
- links (especially JS-triggered)
- popup / modal windows
- forms opened via buttons
- dropdowns
- accordions
- tabs
- sliders/carousels
- burger menus (mobile)
- tooltips
- filters/sort controls

For each UI element:
- trigger the interaction (click, hover, input, etc.)
- verify it works as expected
- verify correct content is shown
- verify no visual breakage occurs
- verify no JS errors appear
- verify behavior on both desktop and mobile

Check for:
- element not clickable
- no reaction on click
- wrong content shown
- broken animation or layout
- popup not opening/closing
- overlay issues (scroll lock, z-index bugs)
- elements hidden or cut off on mobile

Any broken interaction must be reported.

---

### 1.5 Produce visual + UI summary
Create an **HTML summary file** containing:
- page URL
- test date/time
- desktop screenshot
- mobile screenshot
- list of visual differences
- list of UI interaction issues
- severity for each issue
- short conclusion

---

### 2. Server response and robots/indexing checks

#### 2.1 Check HTTP response
Inspect:
- HTTP status code
- redirects
- final URL
- response headers

#### 2.2 Check for critical indexing blockers
These are **Critical** if found unexpectedly:
- `X-Robots-Tag: noindex`
- `X-Robots-Tag: nofollow`
- `meta name="robots" content="noindex"`
- `meta name="robots" content="nofollow"`
- restrictive `googlebot` meta
- incorrect canonical
- unexpected redirects

Any directive blocking indexing must be marked **Critical**.

#### 2.3 Check meta and SEO basics
Inspect:
- `<title>`
- meta description
- robots meta tag
- canonical
- viewport
- hreflang (if present)

---

### 3. Form testing

#### 3.1 Detect forms
Find all forms including:
- visible forms
- popup forms
- dynamically opened forms

#### 3.2 Test submission
For each form:
- fill required fields with valid data
- submit form
- observe frontend validation
- inspect server/network response

#### 3.3 Validate behavior
Check:
- submit works
- validation messages appear correctly
- incorrect input shows errors
- success message is shown
- no JS errors
- no duplicate requests
- backend response is correct

#### 3.4 Report results
For each form include:
- selector/name
- fields
- result (success / error / broken)
- server response
- severity

---

## Output format

### 1. Text summary
- overall result
- issue count by severity
- visual correctness
- UI interaction status
- indexing status
- form functionality status

### 2. HTML report
Must include:
- URL
- screenshots (desktop + mobile)
- visual comparison
- UI interaction results
- SEO/indexing checks
- form testing results
- issue list with severity
- conclusion

---

## Severity rules

### Critical
- noindex / nofollow / X-Robots-Tag blocking indexing
- page inaccessible
- wrong redirect
- core UI not working
- key buttons or popups broken
- key form not submitting

### Major
- broken UI interactions
- major layout mismatch
- mobile UX broken
- validation issues
- backend form errors

### Minor
- small visual differences
- spacing/alignment issues
- minor UI glitches

---

## Example workflow
1. Open page (desktop)
2. Screenshot
3. Open page (mobile)
4. Screenshot
5. Inspect with playwright-screenshot-inspector
6. Compare with reference
7. Test ALL UI interactions (buttons, popups, tabs, etc.)
8. Check response headers and meta tags
9. Detect and test all forms
10. Generate HTML report
11. Return summary

---

## Important constraints
- Do not skip UI interaction testing
- Do not skip mobile
- Do not skip screenshots
- Do not skip form submissions
- Always treat indexing blockers as **Critical**
- Always generate HTML report

---

## Example instruction for the agent
Test the provided page using Playwright.
Use playwright-screenshot-inspector for visual validation.

Follow this order:
1. Compare real page vs reference (desktop + mobile) and record differences.
2. Test ALL UI elements (buttons, popups, accordions, tabs, etc.).
3. Check server response, meta tags, and indexing blockers (Critical if present).
4. Find and submit all forms, validate responses and errors.