Skip to content
OttoTester docs

Reference docs

What a reference doc is

Section titled “What a reference doc is”

A reference doc is a file you attach to an application. The file’s text is extracted and stored on the application, and OttoTester feeds it into the planner on every run.

Use them for anything the planner would benefit from knowing that isn’t easy to convey in the Agent Prompt:

  • A product spec describing what the app is supposed to do.
  • A list of test scenarios the team has agreed should be covered.
  • A .feature file in Gherkin notation, if you already write one.
  • A help article explaining how a feature works.

The Agent Prompt is still the right place for a one-line steer — “focus on checkout” — but anything richer belongs in a reference doc.

Why reference docs sit on the application

Section titled “Why reference docs sit on the application”

Three levels can hold context, and OttoTester puts reference docs at the application level on purpose:

WhereWhat lives there
ApplicationReference docs, application description
VariantBase URL, browser settings, auth fixtures
TemplateSaved run configuration, including the Agent Prompt

A product spec or a feature file describes the app’s contract uniformly — staging and prod should be tested against the same spec. Attaching docs to the application means you upload once and every variant benefits. Environment-specific things — credentials, browser timing — already have natural homes on the variant.

What formats are accepted

Section titled “What formats are accepted”
  • .txt — plain text.
  • .md — Markdown.
  • .docx — Word documents. Text is extracted server-side; formatting is dropped.
  • .pdf — machine-readable PDFs. Scanned or image-only PDFs aren’t read.
  • .feature — Gherkin / Cucumber feature files.

You can add any of these as an uploaded file, or by pasting a link to one (see below). A link can also point to a normal web page — OttoTester reads the page’s main content.

Upload and manage

Section titled “Upload and manage”

On the application page, open the Reference docs tab and drop files into the upload area (or click to pick them). OttoTester extracts the text immediately and the file appears in the list with its name, size, and the date it was uploaded.

To replace a doc, delete the old one and upload the new version. To remove one, click the row’s delete button — the doc is gone from the application’s context the next time the planner runs.

The extracted text is what OttoTester stores; the original file isn’t retained. If you want to revise the wording without re-uploading, the better path is to edit the source doc on your side and re-upload — that keeps your source of truth and OttoTester’s view in sync.

Section titled “Add a reference doc by link”

Sometimes the spec you want to feed OttoTester already lives at a URL — a Confluence or Notion page, a published requirements doc, a PDF on SharePoint. Instead of downloading and re-uploading it, click Add a link next to Upload and paste the link.

  • The link can point to a web page or to any supported file (PDF, Word, Markdown, text, .feature).
  • For a web page, OttoTester saves its main content — the article body, not the site’s menus, sidebars, cookie banners, or footer. This is best-effort; some unusual page layouts won’t read cleanly, and you can always fall back to uploading.
  • OttoTester reads the link once and saves a copy of its text. The doc row shows it came from a link, the link itself, and “Saved from this link on <date>.”

It’s a snapshot — Refresh to update it

Section titled “It’s a snapshot — Refresh to update it”

Adding a link takes a one-time snapshot. OttoTester does not silently re-read the link later, so a link that later changes or stops working can never break a test run. When you want the latest, use the row’s Refresh from link action: it re-reads the page and updates the saved copy and date, and nothing else. It doesn’t regenerate your test suggestions and spends no AI credits.

If a Refresh finds the content has changed, the row shows a small note — “Content changed — re-propose to update suggestions” — with a one-click Re-propose that keeps any suggestions you’ve edited. If a Refresh can’t read the link (it’s offline, needs a sign-in, or 404s), your previous saved copy is left exactly as it was.

Adding a link that’s already saved for this app doesn’t make a second copy — OttoTester tells you it’s already there and points you to Refresh instead.

Reference docs feed candidate tests

Section titled “Reference docs feed candidate tests”

When a reference doc is uploaded, OttoTester runs a candidate-test proposer that reads the doc and suggests test scenarios from it. The suggestions appear on the application’s Candidate tests tab, where you can review, edit, archive, or add to them. See Candidate tests.

The proposed candidates aren’t run as tests — they’re suggestions the planner pulls from during planning, so the test cases it writes line up with what your docs describe.

Section titled “Related”