Skip to content
Testable Docs

Trial File Fundamentals

Experiments Surveys & forms

The **trial file** is the heart of every Testable experiment. It is a spreadsheet where you define every trial, question, and screen that participants will encounter.

Core rules

Section titled “Core rules”
  • Each row is a trial. The term “trial” is used broadly: it covers experimental test trials, instruction screens, practice trials, and survey questions.
  • Each column is a parameter. Columns have self-explanatory names like stim, key, feedback, ITI. You can delete any column you don’t need, with the exception of the required type column.
  • Add any column described in this manual. You can also invent your own custom columns; they won’t affect what participants see but will be recorded in your results file.
  • Column order is not fixed. Reorder columns any way you like.

The type column (required)

Section titled “The type column (required)”

The only required column is type. It tells Testable what kind of trial each row represents.

ValueDescription
testA standard experimental trial. Response and timing data are recorded.
practiceA practice trial. Behaves like test but writes no results row.
learnA study phase trial. Presents content without requiring a response for scoring.
instructionsA screen that displays text to participants before waiting for them to continue.
formA survey question using a form-style response type.

See Trial Types for a full explanation of each type.

Adding stimuli

Section titled “Adding stimuli”

Use the numbered stimulus columns stim1, stim2, stim3, and so on, one column per stimulus, to define what participants see or hear. Two columns work together:

  • stimFormat declares what kind of stimuli the row uses (one value per row): word for text, a file extension such as .png, .mp3, or .mp4 for media, html for custom markup.
  • stim1..stimN carry the content: the text itself, or the filename without its extension (cat for an uploaded cat.png). Media files must be uploaded in the project’s Design/Stimuli tab first.

A trial showing two images side by side would have stimFormat = .png, stim1 = cat, stim2 = dog.

The bare stim column

Section titled “The bare stim column”

There is also a column named just stim, and it is not shorthand for stim1. It is a special multi-role column whose meaning depends on stimFormat: it can hold an inline semicolon-separated list of stimuli, name an uploaded stimulus list to generate trials from (stimFormat = list), or reference an app on html rows. For a single ordinary stimulus, prefer stim1; reach for stim only when you need one of those roles. See the stim column page for the full behaviour.

Defining correct responses

Section titled “Defining correct responses”

Use the key column to specify the correct response for a trial. For keyboard responses, enter the key label (e.g. f or j). For button responses, enter the button label or its position number. For multiple correct answers, separate them with a semicolon.

Organisation columns

Section titled “Organisation columns”

These columns help you structure your results without affecting what participants see:

ColumnPurpose
testTop-level grouping label
subTestSub-grouping label
condition1, condition2, condition3Factor labels for factorial designs
trialNoCustom trial numbering
labelUnique label for a trial, usable in logic (if/then) and variables

Any custom column you add will pass through to your results file without affecting the experiment.

Section titled “Related topics”

Once you understand the basic trial file structure, explore these topics to build more complex experiments:

Next steps

Section titled “Next steps”