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.
  • .feature — Gherkin / Cucumber feature files.

PDF and YAML/JSON aren’t supported yet — PDF extraction quality varies too widely to ship without per-doc tuning, and structured spec files are a different category that needs its own design.

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.

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”