Bug Hunt

Bug Hunt keeps trying to break your site so you do not have to. On a schedule, or when you press Run Scan Now, it opens your site in a headless browser, clicks through it and writes up what broke as draft tickets in the project's queue. You approve the ones you want fixed, and the normal pipeline fixes them: the same plan, implement, review and checks as any other ticket.

When to use it

Use it when you want a regular, hands-off check that your site still works: after a deploy, or every week. It finds errors, not design taste. It works best against a staging copy of your site.

What it needs

• A site address. Open the Bug Hunt page for a project and enter the address of the site to test. Until you do, a project does nothing: no scan runs, by hand or by schedule, and the page tells you to set the address.
• The browser. Bug Hunt uses a headless Chromium browser, which is an optional download. Until it is there, the Bug Hunt page tells you so. See Install the browser.
• A worker. Scans run in the background worker, never in the web app. A schedule needs the worker to be running.

There is no on/off switch for Bug Hunt itself. The address is what turns it on. Deep run, below, is a separate setting that is off by default.

How a scan works

1. It explores, without AI. Starting at your site address, it follows links that stay on your site and clicks the visible buttons and in-page links on each page, up to the limits you set.
2. It records what went wrong. Page errors, console errors, pages that answer with an error, failed requests to your own site, broken links, blank pages, and pages or clicks that time out. Each one keeps the page, the clicks that led there and a screenshot.
3. It groups duplicates, so the same bug is recognized in the next scan.
4. One model call writes the reports. The new problems go to your model provider in a single request. It writes a title, severity, summary, reproduction steps and acceptance criteria for each, or marks noise as ignored. If the call fails, the ticket is written from a fixed template in plainer words.
5. Each new finding becomes a draft ticket with the label bug-hunt. With manual approval it waits for you. With automatic approval it becomes Ready at once and Autopilot picks it up.

A bug you have seen before is not drafted again. A finding you dismiss stays dismissed.

Set it up

1. Install the browser once per install (below).
2. Open Bug Hunt and press Change Settings. Enter the Site address. You can leave out https://. Point it at a staging copy of your site first.
3. Press Run Scan Now, or choose a Schedule (daily or weekly) in the same settings.
4. Review the findings. Approve moves the draft ticket to Ready. Dismiss cancels it and remembers it. You can approve several at once, or all pending findings, and edits you made to a draft are kept. Findings with the same cause on several pages come as one card.

The same settings are also in Settings → Bug Hunt, where each section has its own Save: site, schedule and approval, Deep run, scan limits, sign in, safety rules and deploy checks. Changing them needs the right to edit project settings. Only one scan runs per project at a time, and Stop Scan ends a running one.

Signing in to your site

If the pages you want tested are behind a login, give Bug Hunt a test account: the sign in page address and a user name on the Bug Hunt page, and the password in its own field. The password is stored encrypted like your other credentials and is never shown, logged or sent to the model provider. The scan finds the sign in form by itself, and a two step form (user name, Next, then password) works too. Single sign on, a second factor and a form inside an iframe are not supported. The password belongs to the site it was saved for: if you change the site address, enter the password again.

Watch a scan live

Run Scan Now opens the live view for you. You can also press Watch Live on a running scan. It shows what the scan's browser sees: the page, a box around what it is about to click, and the step in words. The picture refreshes about once a second.

• While you watch, the scan pauses briefly before each click so you can follow it. That time counts toward the scan's time limit. Tick Real time to remove the pause.
• The live view starts after the sign in, so nobody sees the password typed.
• Nothing of it is kept: the pictures are deleted when the scan ends. A finding keeps its own screenshot.
• Anyone who may read the project's tickets may watch, a Viewer included.

Deep run

A standard scan clicks through your site without AI, so it cannot tell that a cart total is wrong or that a form accepts a negative quantity. Deep run is an AI mode for that. It starts the same way, but a model chooses each next step: it reads the page, then clicks, types, opens a page of your site, reports a logical problem or decides it is done.

• Off by default. Turn on the Deep run switch in the Bug Hunt settings. Scans queued from then on, by hand or by schedule, are Deep runs, and each scan shows its mode. Turning it on asks you to confirm once, because every step is a billed model call.
• What it adds. A new kind of finding, Logic problem, with the steps that led to it.
• A step cap. It makes a limited number of model calls per scan (30 by default, 5 to 100), plus one to write up what it found. It stops early when the model has nothing more worth testing.
• What it never does. It never leaves your site, never clicks an element that matches your skip words, never acts on a button whose label commits, spends, sends or removes something (delete, pay, buy, order, confirm, submit, send and similar, a fixed list you cannot empty), never submits a form unless you allowed it, and never types into a password field. Text written on your page is treated as data, so an instruction on your page is ignored.
• What is sent. Each step sends your model provider the page address, its visible text, the labels of what can be clicked or typed into, recent browser errors and the last few steps. Screenshots and the sign in password are never sent.

A Deep run is slower than a standard scan and a model can be wrong. A Logic problem is a lead for a person to look at, which is why findings wait for your approval unless you chose automatic approval.

Safety rules

• It stays on your site. It never follows a link or click to another site, and it skips the paths you list.
• It does not click anything destructive. An element whose text, label, title or link matches the skip words is skipped. The defaults include delete, remove, log out, pay, buy, checkout, send and publish. Add your own, for example the name of a button that charges a card.
• It does not submit forms unless you turn that on. Turn it on only against a staging copy with test data. Dialogs are dismissed and file downloads are not followed.
• Hard limits cap the pages, clicks, total minutes and the time per click.
• Every request is checked. None reaches cloud metadata addresses. On a self-hosted install your own network stays reachable, so it can test an internal site.

On a site that Reqursor hosts for you, the browser reaches public addresses only, so the site you test must be reachable from the internet.

Only point Bug Hunt at sites you own or have permission to test. Do not run it against a site that shows real customer data: a message from your site that contains personal data is part of what the model provider sees.

What it uses in model work

A standard scan makes one model call however many pages it visits, and none when it finds nothing new. The exploring itself uses no model work. It uses CPU and a browser on the machine that runs the worker. A Deep run makes one call per step, up to its cap, plus the one that writes the reports. Calls count against your budgets and show on the usage pages like a planning call. Fixing an approved finding is an ordinary ticket and uses what any ticket uses.

With your own key, your provider bills these calls. See Budgets and cost control.

On Reqursor Credits, these calls use credits, each call reserving and settling on its own. A Deep run is refused while the project's budget is paused. See How credits are counted.

Install the browser

If the browser is missing, Bug Hunt says so and everything else keeps working. It adds about 700 MB of disk.

The Docker build command, with the browser, is the one from the Docker install plus the extra argument:

docker build -f deploy/Dockerfile --build-context artifact=.. --build-arg VERSION=<version> --build-arg BUGHUNT=on -t reqursor-development:<version> .

The bare metal installer downloads the browser once. If that download fails, the install goes on and Bug Hunt says the browser is missing until you run the installer again. See Bare metal & Raspberry Pi.

Check a deployed build

A CI job or deploy step can start a scan of a freshly deployed staging or preview site, wait for it and get a pass or fail verdict. It uses the same API as the dashboard, with an API token that has the scopes tickets:write and tickets:read. Keep the token in your CI's secret store and pass it as REQURSOR_DEV_TOKEN, together with your instance address as REQURSOR_DEV_URL.

reqursor-dev bug-hunt gate --project my-project --base-url https://pr-12.preview.example.com

The command prints one summary line and the reasons. Exit code 0 is a pass and 1 is a fail. Exit code 2 means the scan failed, was stopped, timed out or was refused. Exit code 3 means the project stayed busy with another scan until the timeout, so it is not a verdict and the job can run again.

• What fails the gate. You choose the lowest severity that fails (high, medium, low, or never) and whether it counts only findings new in this scan or every open finding.
• The deployed address must be on the project's own site or listed in the project's allowed deploy hosts.
• The password stays home. A scan of an address on another site explores without signing in, so a preview site never receives the password of your staging site.
• A comment on the pull request is optional. When on, one comment with the verdict is posted and updated by later scans. It uses the project's stored git token.
• Limits. One scan runs per project at a time, and a daily limit caps the scans a CI job may start.

A scan is not deterministic, especially a Deep run. The same build can pass once and fail the next time, and a pass does not mean the site has no bugs. Treat the gate as a safety net next to your tests, and start with failing only on high severity findings that are new.

Limits

• Sign in is one form. There are no multi-step or single sign on flows.
• It finds errors. It does not judge visual design or accessibility.
• A standard scan clicks a fixed set of elements and does not understand your product, so it will not find a bug that only shows with a specific sequence of data entry. A Deep run goes further, but it only types into plain text fields, and what it concludes is the model's judgment.