testosaurusdocs
Browse docs
On this page

Quickstart

Testo typing

Connect your app to a project, invite your testers, and let your coding agent fix what they report.

Before you start: create an account, confirm your email address from the message we send, and create a project. Got a beta invitation? Start on Free first: the invitation upgrades the same account. The setup asks where your widget will run, as a hostname with no port or path, and shows the install snippet with your project's public pk_… app token.

1. Add the script tag

Include the queue stub and the deferred, versioned bundle once, in the layout or page head that every page uses. defer lets the page render while the SDK downloads, and the stub queues Testosaurus.init calls made before the bundle runs, so the tags are safe anywhere in the page. The ?v= hash changes only when the SDK is updated. Using Next.js or Vite? See Next.js and Vite.

html
<script>window.Testosaurus = window.Testosaurus || { q: [] }; window.Testosaurus.init = function (o) { this.q.push(o); };</script>
<script defer src="https://testosaurus.dev/testosaurus.js?v=ecb9344fa761"></script>

2. Initialize

The apiKey is your project's public app token. Copy it from the setup, or at any time from settings → install & domains → App tokens. It identifies the project — there is no separate project name. endpoint is optional and defaults to https://testosaurus.dev.

js
Testosaurus.init({
  endpoint: 'https://testosaurus.dev',
  apiKey: 'pk_your_app_token'
});

3. Add your site to the allowed addresses

Open settings → install & domains → Allowed addresses and use the add button once for every host where you embed the widget (for example app.example.com and www.example.com), with one hostname per entry. Enter hosts only, with no port or path: localhost covers local development on every port, and https:// or :3000 are stripped when you save. Reports from a page whose host is not in the list are rejected, and the widget cannot load its settings there.

How hosts are matched:

  • Exact hostname only: app.example.com covers that host and nothing else.
  • example.com does not cover www.example.com or any other subdomain. Add each host.
  • Wildcards are not supported: *.example.com is rejected as not a valid domain.
  • localhost covers every port, so localhost:3000 and localhost:5173 both work.
  • 127.0.0.1 is a different host from localhost. Add it as well if you open your app that way.
  • Preview-deploy URLs are separate hosts: add each one you use.
  • A project lists up to 20 domains.
  • Reports sent from localhost count toward the monthly report allowance (100 reports on Free) like any other, so send a few realistic ones while you test.

4. Connect your coding agent

Reports are grouped into issues and ranked by impact, which is severity first and then how many reports. Your own coding agent (Claude Code, Codex or any MCP client) reads the top issue with its evidence, fixes it in your repository and runs your tests.

Paste this into your coding agent:

text
Add Testosaurus to this app by following https://testosaurus.dev/docs/connect.md (read it with curl -fsSL).

Your agent opens a page where you sign up or sign in, confirm your email in the same browser if asked, check the code and click Allow. It then creates your project, adds your app's domain, installs the widget (so it covers steps 1 to 3) and connects itself with a Triage key. Nothing secret is copied by hand.

Prefer to do it by hand?

Install the widget with steps 1 to 3, then run the loop once:

  1. Send one realistic bug report from your running app, for example “I click Pay and nothing happens”. It appears in your inbox.
  2. Create a key under settings → agent access → Access keys with kind triage key.
  3. In your repo, run /testosaurus:fix (Claude Code plugin) or /mcp__testosaurus__fix_top_issue.
  4. The agent needs a git repository, a test command it can run and an analyzed bug or confusing issue.

The page Connect your coding agent has the install commands, the key scopes and the safety model.

Got a beta invitation?

Start on Free. Free is not a trial and has no end date. If you are invited to the beta later, the invitation upgrades the same account. More in Pricing & limits.

  • Open the invitation link while you are signed in with the address that was invited. The invitation is tied to one email address, so another account cannot claim it.
  • Your project, tokens and reports stay as they are. Nothing moves or resets.
  • The beta adds Pro-level access: 10 projects, 5 seats, 10,000 reports a month, €3 of included AI analysis a month, 365-day retention and no Testosaurus badge on the widget. It also adds a one-time €10 AI grant. No card is needed and nothing is charged automatically.
  • It lasts until the end of the UTC month that contains the day 60 days after you claim. settings → billing & usage shows the exact end date.
  • When it ends, the account goes back to Free: 1 project, 100 reports a month, €1 of included AI analysis a month and 90-day retention. Reports older than 90 days are removed by the next daily purge. Your projects and tokens stay.
  • An invitation expires after 7 days unless the founder picks a different time, up to 30 days. It cannot be claimed by an account with paid billing.

Done

A button appears in the bottom-right corner. Click it to open the feedback panel. Reports land in your dashboard under the project the token belongs to, where they're grouped into issues with a severity, category and summary. See Reports & distillation.

Testers do not need an account. Share your app’s URL; they use the button in the corner.

If the panel says Feedback isn't available on this page yet., the widget loaded but cannot send yet: the host is missing from your allowed addresses, or bot protection is still being set up for the project. Reload after fixing it, and see Troubleshooting for the console message that names the cause.

To verify the whole loop without touching your app, open the integration playground at https://testosaurus.dev/integration.html?token=pk_… with your app token. It embeds the widget the same way as this guide and sends a real report into your project.

Review your stop-at-limit policy, optional paid overage and usage alerts before inviting testers: see Dashboard & data.

Read the API reference for all options, or see the live demo.

Choose Testo, Bubble or a Feedback pill and preview the panel in Widget customization. Your users can decline screenshot and replay capture while still sending a message.

Next.js and Vite

Bundler apps use the same tags as steps 1 and 2: the queue stub first, then the bundle, then the init call, all in the browser. The ?v= hash is the one shown in step 1.

Next.js (app router)

Put the snippet in app/layout.tsx with next/script and strategy="afterInteractive". The first Script holds the queue stub and the init call, and it comes before the second one, which loads the bundle, so the stub always exists when the bundle starts. Replace pk_your_app_token with your project's token.

tsx
import Script from 'next/script';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script id="testosaurus-init" strategy="afterInteractive">
          {`window.Testosaurus = window.Testosaurus || { q: [] };
window.Testosaurus.init = function (o) { this.q.push(o); };
Testosaurus.init({ endpoint: 'https://testosaurus.dev', apiKey: 'pk_your_app_token' });`}
        </Script>
        <Script src="https://testosaurus.dev/testosaurus.js?v=ecb9344fa761" strategy="afterInteractive" />
      </body>
    </html>
  );
}

Add your production host and localhost to your allowed addresses (step 3). If your site sends a Content Security Policy, allow Testosaurus as described under Content Security Policy.

Vite

Put the three tags in the <head> of index.html. Vite does not bundle classic scripts, so these tags reach the browser unchanged.

html
<script>window.Testosaurus = window.Testosaurus || { q: [] }; window.Testosaurus.init = function (o) { this.q.push(o); };</script>
<script defer src="https://testosaurus.dev/testosaurus.js?v=ecb9344fa761"></script>
<script>Testosaurus.init({ endpoint: 'https://testosaurus.dev', apiKey: 'pk_your_app_token' });</script>

React, Vue, Svelte, Angular and Nuxt apps work the same way: put the three tags in the root HTML template or layout, and keep the init call in the browser, never during server rendering.

Content Security Policy

A site without a Content Security Policy needs nothing here. If your pages send one, allow Testosaurus in these directives:

text
script-src https://testosaurus.dev
connect-src https://testosaurus.dev
frame-src https://testosaurus.dev
style-src 'unsafe-inline'
img-src data:
  • script-src loads the bundle. The queue stub and the init call are inline scripts, so give them a nonce or a hash, or move them into a script file of your own.
  • connect-src lets the widget read its settings and send reports and attachments.
  • frame-src lets the bot-protection challenge load from https://testosaurus.dev/turnstile. The challenge runs inside that frame, so your page does not need challenges.cloudflare.com or 'unsafe-eval'.
  • style-src 'unsafe-inline' is needed because the widget keeps its styles in a <style> element inside its shadow root and sets a few style attributes. A nonce or hash cannot cover style attributes.
  • img-src data: shows the launcher and result artwork, which the bundle embeds as data URIs.

If your policy uses require-trusted-types-for 'script', also allow the two policies the widget creates: trusted-types testosaurus html2canvas-pro. testosaurus builds the panel; html2canvas-pro belongs to the screenshot library, which makes it when it clones the page. Without html2canvas-pro in the list, screenshots are skipped and the report is sent without them. If the challenge frame is blocked, the console says [testosaurus] could not get a verification token; bot protection did not load; check the project sitekey and that the page allows frames from the Testosaurus endpoint (CSP frame-src). and sending fails until frame-src allows https://testosaurus.dev.

Something unclear?Let us know