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.

Testable matches column names without case, so presTime and PRESTIME are the same column. A name with a small typo or extra characters, such as responcewindow or subject_group, is a custom column: Testable does not read it. The trial file editor marks such a column with an amber sign with an exclamation mark (!) next to its name. Click the sign (or press Enter when it has keyboard focus) to open the column menu, which shows the reason, and choose Rename to to change it to the Testable column in one step; the cells keep their values, and one undo reverts the rename. A column named condition or cond gets a blue sign with the letter i: rename it to a free condition slot (condition1 to condition4), or mark it as an independent variable to keep its name. When a project already has results, those results keep the old column name.

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 to condition4Factor 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.

Independent variable tags

Section titled “Independent variable tags”

The trial file editor lets you tag a column as an independent variable (IV). A tagged column shows a solid IV badge in its header. Hovering a column you can tag previews the badge as a dashed outline, so you can see which columns are eligible before you tag one. The condition1 to condition4 columns are tagged by default, since they exist for factorial designs.

You can tag or untag a column from its header menu, using the “Independent variable” item, or from the badge itself. You can also select one or more columns and press Alt+I to toggle the tag on all of them at once. Only your own columns and the condition1 to condition4 columns can be tagged: Testable’s other built-in columns are not eligible. Testable Magic tags the variable columns it creates, so a generated trial file starts with its independent variables already marked.

View-only collaborators see the IV badge on tagged columns, but they cannot add or remove a tag. Tags are saved when you publish the trial file. They travel with the trial file when you duplicate a project or import it from the Library, for copies made after independent variable tags launched. In Insights, the “Group by” list shows tagged columns first, so your independent variables are easy to find when building a figure.

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”