Skip to content
Back to search

assay

The assay plugin, which checks a generated web page after you change it

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/awss1i--assay/badge.svg)](/listings/awss1i--assay)

HTML

<a href="/listings/awss1i--assay"><img src="/api/listings/awss1i--assay/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

pip install assay-ui           # Python 3.10+
uv tool install assay-ui       # no Python 3.10+? uv downloads one
pipx install assay-ui          # installs assay in its own isolated environment

If `pip` isn't found, use `python3 -m pip install assay-ui`. The first run downloads Chromium if needed.

To work on assay itself:

git clone https://github.com/awss1i/assay.git && cd assay
pip install -e ".[dev]"

For coding agents

Install the CLI above first, then follow the **[harness setup →](https://github.com/awss1i/assay/blob/main/docs/harnesses.md)** to add the skill or plugin in any of the fifteen supported harnesses.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 20 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "assay",
  3. "description": "The assay plugin, which checks a generated web page after you change it",
  4. "owner": {
  5. "name": "awss1i",
  6. "url": "https://github.com/awss1i/assay"
  7. },
  8. "plugins": [
  9. {
  10. "name": "assay",
  11. "source": "./plugins/assay",
  12. "description": "Checks a generated web page after you change it, and says what it found either way",
  13. "homepage": "https://github.com/awss1i/assay",
  14. "repository": "https://github.com/awss1i/assay",
  15. "license": "MIT",
  16. "keywords": ["testing", "browser", "verification", "html"],
  17. "category": "testing"
  18. }
  19. ]
  20. }
README.md · README · 220 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <h1 align="center">assay</h1>
  2. <p align="center"><b>English</b> · <a href="https://github.com/awss1i/assay/blob/main/README.zh-CN.md">简体中文</a> · <a href="https://github.com/awss1i/assay/blob/main/README.ja.md">日本語</a> · <a href="https://github.com/awss1i/assay/blob/main/README.ko.md">한국어</a> · <a href="https://github.com/awss1i/assay/blob/main/README.ru.md">Русский</a></p>
  3. <p align="center">
  4. <a href="https://github.com/awss1i/assay/blob/main/pyproject.toml"><img src="https://img.shields.io/badge/python-3.10%2B-7c3aed" alt="python"></a>
  5. <a href="https://github.com/awss1i/assay/blob/main/LICENSE"><img src="https://img.shields.io/badge/licence-MIT-7c3aed" alt="licence"></a>
  6. <a href="https://github.com/sickn33/agentic-awesome-skills"><img src="https://img.shields.io/badge/listed%20in-agentic--awesome--skills-db2777" alt="listed in agentic-awesome-skills"></a>
  7. <a href="https://github.com/TheJambo/awesome-testing"><img src="https://img.shields.io/badge/listed%20in-awesome--testing-db2777" alt="listed in awesome-testing"></a>
  8. <a href="https://github.com/awesome-opencode/awesome-opencode"><img src="https://img.shields.io/badge/listed%20in-awesome--opencode-db2777" alt="listed in awesome-opencode"></a>
  9. </p>
  10. <p align="center">
  11. <a href="#user-content-install">Install</a> · <a href="#user-content-use">Use</a> · <a href="#user-content-benchmarks">Benchmarks</a> · <a href="#user-content-how-it-works">How it works</a> · <a href="#user-content-why">Why</a> · <a href="#user-content-limits">Limits</a> · <a href="#user-content-contributing">Contributing</a> · <a href="#user-content-licence">Licence</a>
  12. </p>
  13. ---
  14. <p align="center"><strong>An agent-native QA CLI for web pages. Deterministic, no tests to write, no LLM.</strong></p>
  15. <p align="center"><code>pip install assay-ui</code></p>
  16. <p align="center">
  17. <img src="https://raw.githubusercontent.com/awss1i/assay/main/docs/run.svg" alt="A terminal running assay on a list
  18. you reorder by dragging. 7 checks planned from the page, 1 passed and 6
  19. failed. The first failure says nothing on the page changed at all, and the
  20. other five say they are the same finding.">
  21. </p>
  22. <p align="center"><i>Checking a drag-to-reorder list with a bug in it.</i></p>
  23. ---
  24. assay opens your page in Chromium, finds every control on it, uses all of
  25. them, and reports what went wrong.
  26. - **No tests to write.** assay builds its checks from the controls it finds
  27. on the page.
  28. - **No LLM.** There's no API key and no cost, and every run gives the same
  29. result.
  30. - **Works with coding agents.** A skill, supported across fifteen harnesses,
  31. has the agent check each page it writes. In Claude Code, Codex, Grok Build
  32. CLI, Devin CLI, Factory Droid, GitHub Copilot CLI and the DeepSeek Harness,
  33. a hook also runs the check automatically after every turn.
  34. - **Groups repeats.** When one bug fails several checks, the later ones say
  35. *same finding as C003* instead of repeating the message.
  36. ---
  37. ## Install
  38. ```bash
  39. pip install assay-ui # Python 3.10+
  40. ```
  41. ```bash
  42. uv tool install assay-ui # no Python 3.10+? uv downloads one
  43. ```
  44. ```bash
  45. pipx install assay-ui # installs assay in its own isolated environment
  46. ```
  47. If `pip` isn't found, use `python3 -m pip install assay-ui`. The first run
  48. downloads Chromium if needed.
  49. To work on assay itself:
  50. ```bash
  51. git clone https://github.com/awss1i/assay.git && cd assay
  52. pip install -e ".[dev]"
  53. ```
  54. ### For coding agents
  55. Install the CLI above first, then follow the
  56. **[harness setup →](https://github.com/awss1i/assay/blob/main/docs/harnesses.md)**
  57. to add the skill or plugin in any of the fifteen supported harnesses.
  58. ---
  59. ## Use
  60. ```console
  61. assay ./my-app # check index.html in this folder
  62. assay ./my-app --report out.html # also write an HTML report with screenshots
  63. assay ./my-app --one-line # short summary, for scripts and agents
  64. ```
  65. The exit code is non-zero if anything failed. Apart from the Chromium download
  66. on the first run, nothing is written to disk unless you ask.
  67. **[The full flags, a worked example, the Python API and the HTML report →](https://github.com/awss1i/assay/blob/main/docs/usage.md)**
  68. ### With coding agents
  69. The **skill** works in all fifteen supported harnesses: Claude Code, DeepSeek
  70. Harness, opencode, Antigravity, Codex App, Codex CLI, Cursor, Devin CLI,
  71. Factory Droid, Gemini CLI, GitHub Copilot CLI, Grok Build CLI, Kimi Code, Pi
  72. and Hermes Agent. It tells your agent to run assay after finishing a page and
  73. end its reply with the result:
  74. ```
  75. assay: checked todo/todo.html, 8 checks, nothing flagged.
  76. ```
  77. The **plugin** adds a hook that runs the check automatically at the end of
  78. each turn that changed a page. The hook works in Claude Code, Codex, Grok
  79. Build CLI, Devin CLI, Factory Droid, GitHub Copilot CLI and the DeepSeek
  80. Harness. Either way, the agent reports what assay found and doesn't change
  81. code because of it unless you ask.
  82. ```
  83. /plugin marketplace add awss1i/assay
  84. /plugin install assay@assay
  85. ```
  86. **[How the skill and plugin work →](https://github.com/awss1i/assay/blob/main/plugins/assay/README.md)**
  87. ---
  88. ## Benchmarks
  89. assay is scored on two sets of pages in this repository, and the scoring
  90. scripts write every number below.
  91. **Pages written by AI.** 225 small web apps an AI wrote from 75 prompts, three
  92. times each, which a person then opened and tried.
  93. <!-- generated -->
  94. assay found the real bug on 15 of the 20 broken pages and flagged 0 of the 205 working pages. [Every page and result](https://github.com/awss1i/assay/blob/main/bench/README.md).
  95. <!-- /generated -->
  96. **Pages with planted bugs.** A separate agent, never told assay exists, took
  97. 10 working apps and planted 5 bugs of its own choosing in a copy of each, then
  98. listed them. assay's rules were developed with these pages in view, so this
  99. score is in-sample.
  100. <!-- planted -->
  101. assay found 12 of the 50 planted bugs and flagged 0 of the 10 original pages. [Every bug and result](https://github.com/awss1i/assay/blob/main/bench/planted/README.md).
  102. <!-- /planted -->
  103. ---
  104. ## How It Works
  105. assay runs in five steps:
  106. 1. Serves the folder on localhost and opens the page in Chromium.
  107. 2. Waits until the page's controls stop changing.
  108. 3. Lists every control the browser renders, including clickable divs, drag
  109. handles and editable regions.
  110. 4. Plans checks from those controls: press every button once and twice,
  111. type empty, ordinary, very long and HTML-laden text into fields, change
  112. every dropdown, draw on canvases, fill in and submit forms, and more.
  113. 5. Runs each check in a fresh tab and compares the page before and after.
  114. assay doesn't know what your page is for, so a button that changes nothing
  115. isn't a failure by itself. Instead it reports places where the page
  116. contradicts itself. For example:
  117. - the page throws an error,
  118. - Undo does nothing on the first press and works on the second,
  119. - a count of items shows 1 when the list is empty,
  120. - a total goes up when an item is added but not down when one is removed,
  121. - `NaN` appears where a number should be,
  122. - nothing on the page responds to any control.
  123. **[Every rule →](https://github.com/awss1i/assay/blob/main/docs/how-it-works.md)**
  124. ---
  125. ## Why
  126. Playwright and Cypress need tests someone wrote. Visual regression needs a
  127. reference screenshot. Asking a model to review the code means reading it, not
  128. running it. assay runs it, with nothing prepared in advance.
  129. | | needs tests written | needs a baseline | runs the program |
  130. |---|---|---|---|
  131. | Playwright / Cypress | yes | no | yes, the parts you wrote |
  132. | Percy / Chromatic | no | **yes** | it screenshots it |
  133. | ask a model to review it | no | no | **no, it reads the source** |
  134. | **assay** | **no** | **no** | **yes, all of it** |
  135. ---
  136. ## Limits
  137. - **It can't check intent.** A page that runs but does the wrong thing, like
  138. a total that adds wrongly, usually passes. To check that, pass acceptance
  139. criteria from Python.
  140. - **Web pages only.** It checks one page at a time, served from a local
  141. folder. It doesn't crawl or log in. The page keeps its internet access
  142. while it's checked, so a page that calls a live API is checked against
  143. whatever that API returns.
  144. - **Built output only.** It won't run `npm install` or your build. Point it
  145. at a source tree and it tells you what to run first.
  146. - **A finished game can look broken.** A game that has ended with no way to
  147. restart stops responding, and that can be reported as nothing responding.
  148. - **Speed.** Most pages take a few seconds to a minute. The benchmark page
  149. has every page's time and the machine they were measured on.
  150. ---
  151. ## Contributing
  152. Report bugs and false alarms as issues, send changes as pull requests, and ask
  153. questions or share ideas in [Discussions](https://github.com/awss1i/assay/discussions). See
  154. **[CONTRIBUTING.md](https://github.com/awss1i/assay/blob/main/CONTRIBUTING.md)**.
  155. ---
  156. ## Licence
  157. MIT.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.