Test file syntax

A test file is one test, kept as a markdown file under .tada/flows/ in your repository. It is optional. Tada keeps every test itself and never writes into your repository, so a test file exists only if your team commits one. Tada reads the files at the commit that deployed. The folder keeps its older name, flows, so files already committed keep working.

The file name without .md is the test’s id within that app. The steps below are the same ones Tada uses for the tests it keeps.

A complete file

---
name: Start a free trial
feature: Free trial
enabled: true
---

Signing up from the pricing page sends the confirmation email.

- goto /pricing
- click Start free trial
- fill Email with [email protected]
- press Enter
  expect: Check your email

Frontmatter

Every key is optional.

Key	What it does
name	The test’s name in reports and on the GitHub check. Without it, the first heading is the name, then the file name.
feature	The feature this test belongs to, named as the ticket. Without it, a new test gets a feature of its own name, and an existing one keeps its feature.
ticket	The ticket id, as your tracker writes it, such as SOL-123. Used only when feature is set.
enabled	false leaves the test out of every check without deleting it.

Lines that are not steps are notes for whoever reads the file. Checks ignore them.

Steps

A step is a line that starts with a dash and a verb.

Verb	What it does	Example
goto	Opens a page. A path opens on the address being checked.	- goto /pricing
click	Clicks something, found by its visible text.	- click Start free trial
fill	Types into a field, found by its label. The label comes before with.	- fill Email with [email protected]
select	Picks an option from a dropdown.	- select Plan with Enterprise
upload	Attaches one of Tada’s sample files to a file field or an upload button. The field or button comes before with.	- upload Invoice with invoice.pdf
press	Presses a key.	- press Enter
hover	Points at something without clicking it.	- hover Enterprise
scroll	Scrolls the page. The words after it are for the reader.	- scroll to the comparison
wait	Holds still, in milliseconds.	- wait 1000
caption	Puts a line of narration on the frame.	- caption Here is the new filter
pause	Stops filming. The browser carries on.	- pause
resume	Starts filming again.	- resume
createInbox	Makes a throwaway email address, written later as ${inbox}.	- createInbox
awaitEmail	Waits for an email, then offers ${magicLink} and ${code}.	- awaitEmail Verify your email
signUp	Finds the sign-up on the page and makes an account with a throwaway address.	- signUp

hover, scroll, wait, caption, pause and resume are camera steps. They change what the film shows and never touch the app.

A line that starts with any other word is not rejected. Tada reads the whole line as text to wait for, so the step fails unless those exact words are on screen. Write fill, not type, and goto, not open.

Expected words

An expect: line sits indented under a step. It holds words that must be on screen after that step.

- click Pay now
  expect: Order confirmed

• An expect: looks for its words anywhere in the visible text, ignoring capital letters, and waits about eight seconds for them.
• A test needs at least one expect:.
• After the last expect:, only camera steps may follow.

Tada does not save a test that breaks either rule. A file that breaks one is still read, and it can pass without proving anything.

Signing in

Sign in inside the test with placeholders, never a real password. Tada fills in the values as it drives.

- pause
- goto /login
- fill Email with {{secret.TADA_TEST_EMAIL}}
- fill Password with {{secret.TADA_TEST_PASSWORD}}
- click Sign in
  expect: Your workspaces
- resume

• {{secret.TADA_TEST_EMAIL}} and {{secret.TADA_TEST_PASSWORD}} are the environment’s main login.
• For a login labelled buyer, write {{secret.TADA_BUYER_EMAIL}} and {{secret.TADA_BUYER_PASSWORD}}. The label goes in capitals, with spaces and symbols turned into underscores.
• pause and resume keep the sign-in off camera.

When checks on an environment start signed in, because you saved a sign-in there with Connect a sign-in, the test does not need these lines.

Email steps

A test can sign itself up in an app with no test login:

- createInbox
- fill Email with ${inbox}
- click Send me a link
- awaitEmail Verify your email
- goto ${magicLink}
  expect: Welcome back

Use ${magicLink} on its own in a goto, never inside a path. Type a code with fill Code with ${code}.

When the email holds more than one link, name the one to open after then open, by the words on its button or part of its address:

- awaitEmail Please sign then open Review and sign
- goto ${magicLink}
  expect: Start signing

When the same words appear twice

Visible text is the right default, because labels survive a redesign. When the same text appears more than once on a page, end the step with a selector in braces:

- click Pay now {selector: [data-testid=pay]}

click, fill, select, upload, scroll and hover use it. The expect: under the step still looks for text.

What a test cannot do

A test has no step to download a file, to accept or dismiss a browser dialog, or to move to another tab. It attaches Tada’s sample files and no others: invoice.pdf, picture.png, photo.jpg, contacts.csv, notes.txt and letter.docx. Dragging works only through verify_feature.