AGENT SKILL

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:

  1. The error is shown to the user: a specific element, not just "the page did not blank".
  2. The app stayed usable: retry works, the form still has its input, navigation is not stuck.
  3. State is honest: reticle_state shows 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.
  4. 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

FarhanS7
FarhanS7/Ecom

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.

★ 0
FarhanS7
FarhanS7/Ecom

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.

★ 0
FarhanS7
FarhanS7/Ecom

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.

★ 0
FarhanS7
FarhanS7/Ecom

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.

★ 0
FarhanS7
FarhanS7/Ecom

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.

★ 0
FarhanS7
FarhanS7/Ecom

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.

★ 0