5.6 KiB
Please update the project's AGENTS.md to document our browser-based UI testing workflow.
Playwright MCP is now available to you and should be used when working on frontend, UI, UX, responsive-layout, JavaScript, HTMX, accessibility, or other browser-visible changes.
Add an appropriate section to AGENTS.md covering the following requirements.
If needed you can install the required modules for it.
Browser and visual testing
Playwright MCP is available for interacting with and inspecting the actual rendered application.
When working on browser-visible changes:
- Use Playwright to open the running Django application and inspect the actual rendered result.
- Do not judge whether a visual change is correct solely by reading Django templates, HTML, SCSS/CSS, or JavaScript.
- After significant UI changes, reload the relevant page and inspect the result in the browser.
- Use screenshots when evaluating visual appearance, spacing, typography, sizing, alignment, colour, hierarchy, overflow, or responsive behaviour.
- Use the accessibility/DOM representation where it is more appropriate for understanding page structure, controls, labels, state, and interactions.
- Test relevant interactions rather than assuming they work from reading the implementation.
- Check browser console errors after changes involving JavaScript or HTMX.
- Verify important HTMX interactions in the browser.
- Test both desktop and mobile-sized viewports when the affected interface is responsive.
- When appropriate, test intermediate viewport widths as well rather than only the two extremes.
- Do not consider a visual task complete until the rendered result has actually been inspected.
When reporting findings from browser inspection, distinguish between:
- problems actually observed in the rendered application;
- accessibility or functional problems discovered through browser inspection;
- optional design suggestions.
Do not present subjective redesign suggestions as bugs.
Do not redesign unrelated parts of the application simply because browser inspection reveals opportunities for improvement. Keep changes within the requested scope unless explicitly asked otherwise.
Authentication and demo account
The application has a dedicated demo/test account intended for development and browser testing.
Playwright may use this account when authentication is required.
The demo account may be used to:
- navigate authenticated parts of the application;
- create test data;
- edit test data belonging to the demo user;
- delete test data belonging to the demo user;
- exercise forms and interactive features;
- test authenticated HTMX/browser behaviour.
Never modify data belonging to other users.
Prefer reusing an existing authenticated Playwright browser session when one is available rather than repeatedly logging in.
The demo account credentials should not be written into AGENTS.md, source code, committed configuration, or other repository files. They can be supplied interactively when authentication is required.
Do not copy authentication cookies, session tokens, CSRF tokens, passwords, or other credentials into committed files.
If Playwright authentication state is ever exported to a file, store it in a dedicated location such as:
playwright/.auth/
and ensure that directory is excluded by .gitignore.
Browser testing behaviour
Browser access is a verification and debugging tool, not permission to make arbitrary changes.
When asked to inspect something without modifying it:
- browse the application;
- reproduce the relevant state;
- inspect it;
- take screenshots if useful;
- report findings;
- do not change project files.
When asked to implement a browser-visible change:
- inspect the current rendered state when useful;
- implement the requested change;
- reload/open the affected page;
- inspect the rendered result;
- exercise the relevant interaction if applicable;
- check for browser/console errors;
- inspect responsive behaviour where relevant;
- fix problems introduced by the change before considering the task complete.
For visual verification, prefer observations from the actual rendered application over assumptions derived from source code.
If the Django development server is not running, determine the project's normal development command from the repository rather than inventing a new development setup. Starting the existing development server for browser testing is allowed when appropriate.
Do not alter production configuration merely to make browser testing easier.
Accessibility
Use browser testing to help catch accessibility regressions when working on UI.
Where relevant, verify:
- semantic controls and headings;
- accessible names and labels;
- keyboard-operable interactive elements;
- visible focus behaviour;
- sensible form validation/error presentation;
- appropriate ARIA state where custom controls require it;
- obvious colour/contrast or readability problems;
- behaviour at narrow/mobile viewport sizes.
Do not treat the accessibility tree alone as proof that the visual interface is correct. Likewise, do not treat a screenshot alone as proof that the interface is accessible. Use the appropriate browser information for each.
Please integrate these rules cleanly into the existing AGENTS.md rather than blindly appending duplicate or conflicting instructions.
Preserve any existing useful project-specific instructions.
Before editing, read the current AGENTS.md if one exists and adapt the new section to its existing structure and terminology.
Afterwards, show me the resulting section or summarise exactly what you added. Do not make unrelated project changes.