test-error-states
Force the states a happy-path run never reaches (a failing API, an empty list, a slow request, a timeout, an expired session, a toast that auto-dismisses) and check the UI actually handles them. Use when error handling was written but never run, when a loading or empty state needs verifying, when a bug only happens on a slow connection, or when a timer, poll, debounce or retry needs testing without sleeping.
- License 许可
- Apache-2.0
- 所属仓库
- FarhanS7/Ecom
- 最近更新
- 2026-10-16
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- test-error-states
- license
- Apache-2.0
- metadata
- { "version": "2.13.1", "homepage": "https://www.reticle.sh", "repository": "https://github.com/reticlehq/reticle" }
- description
- Force the states a happy-path run never reaches (a failing API, an empty list, a slow request, a timeout, an expired session, a toast that auto-dismisses) and check the UI actually handles them. Use when error handling was written but never run, when a loading or empty state needs verifying, when a bug only happens on a slow connection, or when a timer, poll, debounce or retry needs testing without sleeping.
03 SKILL.md 正文
The error state has never run
Every app has a catch block nobody has executed and an empty state nobody has seen. They are written from imagination, shipped untested, and discovered by a user on a bad day.
Reticle can force those conditions in the running app. Not installed? RETICLE_INSTALL_SOURCE=npx_skill npx @reticlehq/server@latest init, then the install-and-verify skill.
Read this before you start: network mocking needs a driven browser
reticle_network_mock applies mocks through CDP, and the always-on SDK cannot do it. A pooled lease is not enough either: reticle_lease returns { ok: false, reason: "no-cdp-provider" }.
Your route is RETICLE_CDP_URL pointed at a Chrome started with remote debugging:
# macOS — the user runs this once, in their own Chrome
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
RETICLE_CDP_URL=http://localhost:9222 npx @reticlehq/server@latest mcp
If that is not set up, say so in one line and offer the clock half of this skill anyway: reticle_clock needs none of it. What you may not do is drive the happy path, watch it pass, and report that error handling works.
Force a failure
reticle_run({ tool: "reticle_network_mock", sessionId, args: {
mocks: [{ urlContains: "/api/deploys", status: 500 }],
}})
Then drive the flow and name the recovery you expect before you act:
reticle_act_and_wait({ sessionId, ref, action: "click", until: { kind: "allOf", predicates: [
{ kind: "element", query: { testid: "error-banner" } },
{ kind: "console", level: "error", absent: true },
]}})
Note the second predicate. A UI that "handles" an error by logging an uncaught exception has not handled it. Clear mocks with { clear: true } when you are done, or every later check runs against a lie.
Worth forcing, in rough order of how often they are broken: 500, a 4xx with a real error body, an empty 200 ([], the empty state), a malformed payload, and a request that never resolves (the spinner that spins forever).
Skip time instead of sleeping
reticle_clock({ sessionId, freeze: true })
reticle_clock({ sessionId, advanceMs: 5000 })
reticle_clock({ sessionId, reset: true })
Toasts that auto-dismiss, debounced search, polling, session timeouts, retry backoff. All of these are normally verified by sleeping, which is slow and flaky in equal measure. A timing assertion is a statement about the machine, so it passes on your laptop and fails in CI.
Freeze, advance by exactly the interval, assert the consequence. Same result on a fast laptop and a loaded runner. Always reset when you finish, or a frozen clock silently breaks everything that runs after you.
What to assert
The recovery, not the absence of a crash:
- The error is shown to the user: a specific element, not just "the page did not blank".
- The app stayed usable: retry works, the form still has its input, navigation is not stuck.
- State is honest:
reticle_stateshows the failure, not a half-applied optimistic update. A UI that rolled back visually while the store kept the optimistic value is the classic bug here, and only the store read finds it. - No uncaught error in the console.
Honesty
Mocking changes the app's world, so a verdict taken under a mock is a statement about the mocked condition and nothing else. Say which mock was active when you report a pass, and clear every mock and reset the clock before handing back. An audit that leaves a 500 pinned on /api/deploys breaks the next person's session and looks like a real outage.
Capability reference: curl https://docs.reticle.sh/capabilities.md. Everything else: curl https://docs.reticle.sh/llms.txt.
04 同仓库更多 Skills
verify-unattended
Install, instrument and verify a web app end to end without pausing for a human. Use in an autonomous or goal-mode agent, in CI, or in any client that asks for approval on every command: it never says "restart your client" or "open a browser", because it takes a route that needs neither. Prefer the normal install-and-verify skill when a human is present and can answer.
verify-ui-change
Check that a change to a web app actually works in the running app before calling it done. Drives the real page and returns a pass/fail verdict with the request that fired, the state that moved, and the file:line to fix. Use after editing a component, a form, a route, or an API call; when you have said "fixed" but have not opened the app; when the user asks "does it actually work?"; or when a change looks right on screen and you cannot prove it.
replay-user-flows
Turn a user journey you just clicked through into a saved regression check that re-runs deterministically, with no model in the loop and no test code to write. Use when you have driven the same flow twice, when the user wants regression coverage without a Playwright suite, when a refactor needs proving against every existing journey, or when re-verifying by hand is costing a full drive every time.
install-and-verify
Verify that a web app change actually works by driving the running app from the inside (DOM, network, routing, console, framework state) instead of screenshots or guessing. Use after any user-facing change, when a fix is claimed but unproven, when a test passes but the UI is broken, or when you need a real verdict rather than "looks right". Also use to install and wire up Reticle in a project that does not have it yet.
fix-what-i-pointed-at
Pick up the bugs a human flagged by pointing at them in the running app, each arriving with the element, the note they typed, and the source file and line. Use when the user says they marked or flagged something, when starting a session on an app someone has been clicking through, when a designer or PM has left feedback in the UI, or when the user describes a problem as "that button there" without saying which file.
false-green-tests
Find out why the tests pass but the app is broken. Catches false greens: a green suite over a feature that does not work, a mocked API standing in for a real one, an assertion that holds no matter what the app does, a click handler wired to nothing. Use when the suite is green and the user says it is broken, when a test never fails, when coverage looks fine but bugs still ship, or before trusting a passing run you did not watch.