Web App Testing
Testing a local web application means proving, with evidence, that a page
renders, that its controls do what they claim and that nothing fails silently
in the console or on the network. The agent does the clicking; the user gets a
report with screenshots and exact failure locations.
Two instruments are available. The built-in browser tool (headless Chromium
with navigate, snapshot, click, type, screenshot, console,
network) is the fastest way to explore and run one-off interactive checks.
Playwright Python scripts are the right choice when the same flow must run
again (regression after each change, CI, several pages in a loop). The
playwright-browser skill covers the generic browser tool in depth; this skill
is about testing a project's own app.
Workflow
1. Get the app running
- If the project has a dev server, start it with
start_app or
open_preview; both pick a free port and return the URL. Never hard-code
the ports 5173-5176, 8765-8768 or 18790-18793: they belong to the Navin
runtime.
- For a Playwright script that needs one or more servers alive only for the
duration of the run, wrap it with
scripts/with_server.py. Run
python3 scripts/with_server.py --help first. Each --server "cmd" pairs
with a --port N; the script waits until each port accepts a connection
(default 30 s per server, --timeout to change), runs the command written
after --, then stops every server (SIGTERM, then SIGKILL after 5 s) and
exits with the inner command's exit code.
python3 scripts/with_server.py \
--server "cd backend && python3 -m uvicorn app:api --port 8100" --port 8100 \
--server "cd frontend && npm run dev -- --port 4300" --port 4300 \
-- python3 tests/e2e/smoke.py http://127.0.0.1:4300
- Static HTML needs no server: open it with a
file:// URL. The file content
can be read directly to find ids and labels before launching anything.
2. Reconnaissance before action
Never guess selectors. Load the page, wait for the network to go idle, then
look at what is actually rendered:
- With the
browser tool: navigate to the URL, then snapshot to list the
interactive elements with numeric refs, and screenshot to see the layout.
- With Playwright: run
examples/discover_elements.py <url>. It prints JSON
with every button, link, input and heading (text, role, id, name, type,
visibility) plus the page title, so stable selectors can be chosen.
Prefer selectors in this order: get_by_role with an accessible name,
get_by_label, get_by_text, data-testid, then id, then CSS. Avoid
position-based or auto-generated class selectors; they break on the next
build.
3. Drive the flow
For each scenario (login, create an item, filter a list, submit a form):
- Perform the action with the discovered selector.
- Wait for an observable consequence (
wait_for_selector, URL change, a
toast, a row count), not for a fixed sleep. A wait_for_timeout is a last
resort and must be justified in the report.
- Assert the outcome visibly: the text appeared, the input is empty, the
table has N rows.
- Take a screenshot after each meaningful state (
page.screenshot(path=..., full_page=True) or the browser tool's screenshot). Save screenshots in
a dedicated folder such as .navin/test-evidence/ and name them by step.
examples/static_page.py <url> shows a complete scripted flow against a
local HTML file: load, screenshot, fill a form, click submit, screenshot
again, print a JSON summary.
4. Capture what the user cannot see
A page can look fine while it is broken underneath. Always collect:
- Console messages of type
error and warning, plus uncaught pageerror
exceptions.
- Failed network requests:
requestfailed events and responses with status
400 or above, with method, URL and status.
examples/console_errors.py <url> wires all these listeners, loads the page,
optionally clicks an element given with --click <selector>, waits for the
network to settle and prints a JSON object with console, page_errors and
failed_requests. The browser tool offers the same data through its
console and network actions after a navigate.
Treat a 404 on a favicon as noise; treat a 500 on an API call or a React
"Cannot read properties of undefined" as a failure even when the UI looks
normal.
5. Report
Write the report for someone who was not watching. Include:
- Environment: URL, server command, browser, viewport, commit or branch.
- Steps performed, numbered, each with the selector used and the screenshot
path.
- Findings: what passed, with the evidence that proves it.
- Failures: the step, the selector, the expected and observed state, the
exact console line or failed request (method, URL, status), and the
screenshot taken at that moment.
- Anything skipped and why (no test account, feature behind a flag, flaky
third-party widget).
Never report a step as passed without evidence from the run. If a check could
not be executed, say so instead of inferring the result.
Writing a Playwright script
Keep scripts small and parameterised by URL so they run under
scripts/with_server.py or against an already running server. Pattern:
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
browser = p.chromium.launch(headless=True)
page = browser.new_page(viewport={"width": 1280, "height": 800})
page.goto(url)
page.wait_for_load_state("networkidle")
page.get_by_role("button", name="Save").click()
page.wait_for_selector("text=Saved")
page.screenshot(path="evidence/after-save.png", full_page=True)
browser.close()
Rules:
- Always headless, always close the browser, always exit non-zero on a
failed assertion so
with_server.py propagates it.
- Print machine-readable output (JSON) when another step will consume it;
print prose only for the human.
- If
playwright is not installed, the examples print a one-line
installation hint (pip install playwright && playwright install chromium)
and exit 2 instead of a stack trace. Do the same in new scripts.
- Do not store credentials in scripts; read them from environment variables
or use the
browser tool's secret references.
Bundled files
scripts/with_server.py: start servers, wait for ports, run a command,
tear everything down, propagate the exit code.
examples/discover_elements.py: list interactive elements of a page as
JSON for selector discovery.
examples/console_errors.py: capture console errors, page exceptions and
failed requests as JSON.
examples/static_page.py: scripted form flow against a file:// page with
screenshots.
examples/_playwright.py: shared lazy import used by the three examples;
prints the installation hint and exits 2 when Playwright is missing.
Pitfalls
- Inspecting the DOM before
networkidle on a client-rendered app returns an
empty shell; wait first.
- A dev server that prints "ready" may still refuse connections for a second;
with_server.py polls the port, do not rely on log lines.
- Headless viewports default to 1280x720; set the viewport explicitly when
the layout is responsive, and test at least one narrow width.
- Screenshots of pages with animations can differ between runs; wait for the
final state or disable animations with
reduced-motion emulation.
1---2name: webapp-testing3description: Tests a local web application end to end - start the server under test, discover selectors in the rendered DOM, drive the pages with the built-in browser tool or Playwright scripts, capture console errors, failed requests and screenshots, then report findings. Use when the user asks to "test this web app", "check the login flow works", "find JavaScript errors on the page" or "verify the frontend after my change". In French "teste mon application web", "lance le serveur de dev puis les tests" or "vérifie le parcours de connexion".4metadata:5 source: https://skillmd.com/skills/navinspire-ia/webapp-testing6 navin:7 emoji: 🧪8 category: development9---1011# Web App Testing1213Testing a local web application means proving, with evidence, that a page14renders, that its controls do what they claim and that nothing fails silently15in the console or on the network. The agent does the clicking; the user gets a16report with screenshots and exact failure locations.1718Two instruments are available. The built-in `browser` tool (headless Chromium19with `navigate`, `snapshot`, `click`, `type`, `screenshot`, `console`,20`network`) is the fastest way to explore and run one-off interactive checks.21Playwright Python scripts are the right choice when the same flow must run22again (regression after each change, CI, several pages in a loop). The23`playwright-browser` skill covers the generic browser tool in depth; this skill24is about testing a project's own app.2526## Workflow2728### 1. Get the app running2930- If the project has a dev server, start it with `start_app` or31 `open_preview`; both pick a free port and return the URL. Never hard-code32 the ports 5173-5176, 8765-8768 or 18790-18793: they belong to the Navin33 runtime.34- For a Playwright script that needs one or more servers alive only for the35 duration of the run, wrap it with `scripts/with_server.py`. Run36 `python3 scripts/with_server.py --help` first. Each `--server "cmd"` pairs37 with a `--port N`; the script waits until each port accepts a connection38 (default 30 s per server, `--timeout` to change), runs the command written39 after `--`, then stops every server (SIGTERM, then SIGKILL after 5 s) and40 exits with the inner command's exit code.4142```bash43python3 scripts/with_server.py \44 --server "cd backend && python3 -m uvicorn app:api --port 8100" --port 8100 \45 --server "cd frontend && npm run dev -- --port 4300" --port 4300 \46 -- python3 tests/e2e/smoke.py http://127.0.0.1:430047```4849- Static HTML needs no server: open it with a `file://` URL. The file content50 can be read directly to find ids and labels before launching anything.5152### 2. Reconnaissance before action5354Never guess selectors. Load the page, wait for the network to go idle, then55look at what is actually rendered:5657- With the `browser` tool: `navigate` to the URL, then `snapshot` to list the58 interactive elements with numeric refs, and `screenshot` to see the layout.59- With Playwright: run `examples/discover_elements.py <url>`. It prints JSON60 with every button, link, input and heading (text, role, id, name, type,61 visibility) plus the page title, so stable selectors can be chosen.6263Prefer selectors in this order: `get_by_role` with an accessible name,64`get_by_label`, `get_by_text`, data-testid, then id, then CSS. Avoid65position-based or auto-generated class selectors; they break on the next66build.6768### 3. Drive the flow6970For each scenario (login, create an item, filter a list, submit a form):7172- Perform the action with the discovered selector.73- Wait for an observable consequence (`wait_for_selector`, URL change, a74 toast, a row count), not for a fixed sleep. A `wait_for_timeout` is a last75 resort and must be justified in the report.76- Assert the outcome visibly: the text appeared, the input is empty, the77 table has N rows.78- Take a screenshot after each meaningful state (`page.screenshot(path=...,79 full_page=True)` or the `browser` tool's `screenshot`). Save screenshots in80 a dedicated folder such as `.navin/test-evidence/` and name them by step.8182`examples/static_page.py <url>` shows a complete scripted flow against a83local HTML file: load, screenshot, fill a form, click submit, screenshot84again, print a JSON summary.8586### 4. Capture what the user cannot see8788A page can look fine while it is broken underneath. Always collect:8990- Console messages of type `error` and `warning`, plus uncaught `pageerror`91 exceptions.92- Failed network requests: `requestfailed` events and responses with status93 400 or above, with method, URL and status.9495`examples/console_errors.py <url>` wires all these listeners, loads the page,96optionally clicks an element given with `--click <selector>`, waits for the97network to settle and prints a JSON object with `console`, `page_errors` and98`failed_requests`. The `browser` tool offers the same data through its99`console` and `network` actions after a `navigate`.100101Treat a 404 on a favicon as noise; treat a 500 on an API call or a React102"Cannot read properties of undefined" as a failure even when the UI looks103normal.104105### 5. Report106107Write the report for someone who was not watching. Include:108109- Environment: URL, server command, browser, viewport, commit or branch.110- Steps performed, numbered, each with the selector used and the screenshot111 path.112- Findings: what passed, with the evidence that proves it.113- Failures: the step, the selector, the expected and observed state, the114 exact console line or failed request (method, URL, status), and the115 screenshot taken at that moment.116- Anything skipped and why (no test account, feature behind a flag, flaky117 third-party widget).118119Never report a step as passed without evidence from the run. If a check could120not be executed, say so instead of inferring the result.121122## Writing a Playwright script123124Keep scripts small and parameterised by URL so they run under125`scripts/with_server.py` or against an already running server. Pattern:126127```python128from playwright.sync_api import sync_playwright129130with sync_playwright() as p:131 browser = p.chromium.launch(headless=True)132 page = browser.new_page(viewport={"width": 1280, "height": 800})133 page.goto(url)134 page.wait_for_load_state("networkidle")135 page.get_by_role("button", name="Save").click()136 page.wait_for_selector("text=Saved")137 page.screenshot(path="evidence/after-save.png", full_page=True)138 browser.close()139```140141Rules:142143- Always headless, always close the browser, always exit non-zero on a144 failed assertion so `with_server.py` propagates it.145- Print machine-readable output (JSON) when another step will consume it;146 print prose only for the human.147- If `playwright` is not installed, the examples print a one-line148 installation hint (`pip install playwright && playwright install chromium`)149 and exit 2 instead of a stack trace. Do the same in new scripts.150- Do not store credentials in scripts; read them from environment variables151 or use the `browser` tool's secret references.152153## Bundled files154155- `scripts/with_server.py`: start servers, wait for ports, run a command,156 tear everything down, propagate the exit code.157- `examples/discover_elements.py`: list interactive elements of a page as158 JSON for selector discovery.159- `examples/console_errors.py`: capture console errors, page exceptions and160 failed requests as JSON.161- `examples/static_page.py`: scripted form flow against a `file://` page with162 screenshots.163- `examples/_playwright.py`: shared lazy import used by the three examples;164 prints the installation hint and exits 2 when Playwright is missing.165166## Pitfalls167168- Inspecting the DOM before `networkidle` on a client-rendered app returns an169 empty shell; wait first.170- A dev server that prints "ready" may still refuse connections for a second;171 `with_server.py` polls the port, do not rely on log lines.172- Headless viewports default to 1280x720; set the viewport explicitly when173 the layout is responsive, and test at least one narrow width.174- Screenshots of pages with animations can differ between runs; wait for the175 final state or disable animations with `reduced-motion` emulation.