assay README

The project's README from github.com/awss1i/assay. As one markdown file: README.md.

assay

python licence X

Drives your web page in a real browser and tells you what broke. No tests to write, no LLM.

A terminal running assay on a list you reorder by dragging. 7 checks planned from the page, 1 passed and 6 failed. The first failure says nothing on the page changed at all, and the other five say they are the same finding.

Checking a drag-to-reorder list with a bug in it. pip install assay-ui

assay opens your page in Chromium, finds every control on it, uses all of them, and reports what went wrong.

Contents

Install

pip install assay-ui           # Python 3.10+

uv tool install assay-ui       # no Python 3.10+? uv downloads one

pipx install assay-ui          # its own environment, for when pip says "externally managed"

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 → to add the skill or plugin in any of the fifteen supported harnesses.

Use

assay ./my-app                    # check index.html in this folder
assay ./my-app --report out.html  # also write an HTML report with screenshots
assay ./my-app --one-line         # short summary, for scripts and agents

This repository includes a drawing program whose Undo is broken:

$ assay bench/programs/dsh/gpt-oss-120b/37_draw2
24 case(s) planned, 24 carried out, 23 passed, 1 failed

C016 [FAILED] draw on canvas twice, then press Undo twice
    → pressing this twice from the same starting point, the first press changed nothing and the second did, so it reacts one press late

The exit code is non-zero if anything failed, and nothing is written to disk unless you ask.

The full flags, the Python API and the HTML report →

With coding agents

The skill works in all fifteen supported harnesses: Claude Code, DeepSeek Harness, opencode, Antigravity, Codex App, Codex CLI, Cursor, Devin CLI, Factory Droid, Gemini CLI, GitHub Copilot CLI, Grok Build CLI, Kimi Code, Pi and Hermes Agent. It tells your agent to run assay after finishing a page and end its reply with the result:

assay: checked todo/todo.html, 8 checks, nothing flagged.

The plugin (Claude Code and the DeepSeek Harness) adds a hook that runs the check automatically at the end of each turn that changed a page. Either way, the agent reports what assay found and doesn't change code because of it unless you ask.

/plugin marketplace add awss1i/assay
/plugin install assay@assay

How the skill and plugin work →

Benchmarks

Scored on two sets of pages in this repository. Every number here is written by the scoring script, never typed by hand.

Pages written by AI. 225 small web apps an AI wrote from 75 prompts, three times each, which a person then opened and tried.

Found the real bug on 15 of the 20 broken pages, with 0 of the 205 working pages flagged. Every page and result.

Pages with bugs added on purpose. 10 working apps, each copied with 5 bugs added and written down.

Found 12 of the 50 added bugs, with 0 of the 10 original pages flagged. Every bug and result.

How It Works

  1. Serves the folder on localhost and opens the page in Chromium.
  2. Waits until the page's controls stop changing.
  3. Lists every control the browser renders, including clickable divs, drag handles and editable regions.
  4. Plans checks from those controls: press every button once and twice, type empty, ordinary, very long and HTML-laden text into fields, change every dropdown, draw on canvases, fill in and submit forms, and more.
  5. Runs each check in a fresh tab and compares the page before and after.

assay doesn't know what your page is for, so a button that changes nothing isn't a failure by itself. Instead it reports places where the page contradicts itself. For example:

Every rule →

Why

Playwright and Cypress need tests someone wrote. Visual regression needs a reference screenshot. Asking a model to review the code means reading it, not running it. assay runs it, with nothing prepared in advance.

needs tests written needs a baseline runs the program
Playwright / Cypress yes no yes, the parts you wrote
Percy / Chromatic no yes it screenshots it
ask a model to review it no no no, it reads the source
assay no no yes, all of it

Limits

Contributing

Report bugs and false alarms as issues, send changes as pull requests, and ask questions in Discussions. See CONTRIBUTING.md.

Licence

MIT.

assay (awss1i/assay)

Searching Database…

107 ·GitHub
Assay
Что это?'assay' — инструмент, который открывает вашу веб-страницу в настоящем браузере Chromium, автоматически нажимает все кнопки, заполняет все поля и задействует каждый найденный элемент управления, а затем сообщает, где страница противоречит сама себе — без написания тестов и без LLM.
Это то же самое, что Playwright или Cypress?Нет — Playwright и Cypress прогоняют тесты, написанные человеком, а assay сам строит проверки, обнаруживая элементы управления на странице, поэтому вам нечего скриптовать.
Как установить и запустить?Установите командой 'pip install assay-ui' (или 'python3 -m pip install assay-ui', если pip не находится); при первом запуске при отсутствии Chromium он скачается автоматически, затем укажите на папку, где раздаётся ваша страница.
Нужен ли API-ключ или LLM, чтобы им пользоваться?Нет — в assay нет ни LLM, ни API-ключа, ни платы за использование, и каждый прогон на одной и той же странице даёт один и тот же результат.
Поймает ли он каждый баг на моей странице?Нет — он не судит о намерениях, поэтому страница, которая работает без сбоев, но считает неверный результат (например, неправильно складывает итог), обычно проходит; к тому же за раз он проверяет только одну локально раздаваемую страницу, без логина, живых сетевых вызовов и шага сборки.
Насколько точно assay ловит настоящие баги?На 225 мини-приложениях, написанных AI, он нашёл настоящий баг в 15 из 20 сломанных страниц без единого ложного срабатывания на 205 работающих; на приложениях с намеренно добавленными багами он нашёл 12 из 50 добавленных багов без единого ложного срабатывания на оригиналах.
Работает ли он автоматически с агентами кодинга вроде Claude Code?Да — скилл позволяет запускать его после того, как любой из 15 поддерживаемых харнессов (Claude Code, DeepSeek Harness, opencode, Codex, Cursor, Gemini CLI и другие) напишет страницу, а плагин для Claude Code и DeepSeek Harness запускает проверку автоматически после каждого хода, меняющего страницу.
Какие проблемы он на самом деле помечает?Он ищет самопротиворечия страницы: выброшенные ошибки, кнопку Undo, которая ничего не делает, а потом внезапно работает, счётчик элементов, показывающий 1 при пустом списке, итоги, которые растут, но не убывают, случайные значения NaN или полное отсутствие реакции страницы.
Почему бы просто не попросить LLM отревьюить код?Чтение кода говорит вам, что он должен делать, а не что он реально делает при запуске; assay вместо этого раздаёт страницу, взаимодействует с ней в настоящем браузере и сообщает о наблюдаемых несоответствиях — без модели и без затрат на API.
What are similar projects?testsprite-cli, playwright, SeleniumBase, agentic-playwright, playwright-cli, ouroboros, pstack-claude, reverse-api-engineer
Which topics is it in?end-to-end-testing, qa, pip, testing-tools, test-automation, codex-cli, chrome, github-copilot, gemini-cli, code-generation, playwright, opencode
Creator
awss1i
Size
0.8 MB
Stars
107
Updated
CommitOct 18Releasev0.3.1Oct 17
Age
1mo
Commits · 90 Days