Build an Experiment, Start to Finish

This journey is for anyone building their first Testable experiment: a task with stimuli, timed responses, and scored answers. It walks the manual in the order the concepts build on each other, and ends with you publishing a working experiment and knowing where your data lands.

Keep the Columns Reference open alongside every step. Each column named on these pages has its own reference page with syntax, accepted values, defaults, and examples verified against the Testable runtime.

Learn the foundations

1. Trial File Fundamentals. Take away the core rules: each row is a trial, each column is a parameter, and type is the only required column. Everything else in this journey builds on that model.

2. Trial Types. Learn what test, practice, learn, instructions, and form each do. For this journey you will mostly use test, practice, and instructions; the form world has its own journey.

Build your trials

3. Instructions Trials. The title and content columns give you welcome screens, block instructions, and debrief text. Nearly every experiment starts with one of these rows.

4. Define and Position Stimuli. The stim columns plus stimFormat, stimSize, and stimPos control what participants see and where. Skip the CSS styling and cross-trial audio sections on a first pass.

5. Responses in Experiments. buttons and key cover most tasks, and the key column doubles as the correct answer for accuracy scoring. Skip the microphone, sort, and drag sections on a first pass.

6. Timing Parameters. ITI, ISI, presTime, and responseWindow control the temporal structure of a trial, including when responses are enabled and when a trial times out. For sequential designs where several stimuli share a screen, stimScreens states the grouping.

7. Feedback. The feedback column shows outcome-specific messages (correct:, incorrect:, timeout:) with %variable% placeholders, timed by feedbackTime. Skip on a first pass if your design has no trial-by-trial feedback, but read it before building practice blocks.

Go deeper (skippable on a first pass)

8. Generating Trials from Stimulus Lists. One row plus an uploaded list expands into one trial per item. Come back when you catch yourself writing many near-identical rows.

9. Randomisation. random and randomBlock shuffle trials and blocks, and sampling specs in the trialOrder cell show each participant a subset. Within a trial, stimOptions shuffles stimulus order freely and stimOrder does it under constraints (pairs, screens, pinned positions). Skippable while you build, but most designs need it before real data collection.

10. Staircase Experiments. The staircase column adapts difficulty to performance. Only needed for threshold estimation and similar adaptive designs.

11. Scripts and Custom HTML Stimuli. The Advanced Techniques pages: custom JavaScript in trials, and whole trials handed over to your own HTML page. Reach for these last, when no built-in column expresses what you need.

Check and configure

12. Previewing Your Trials. Run your trial file from the editor, one trial at a time, to check stimuli, responses, timing, and feedback before anything goes live.

    Caution

    The previewer shows trials in file order: randomisation, subject groups, and breaks are not applied there. Conditional logic does work, so you can test branching, but check randomised order in a real run.

13. General Settings. Project-wide behaviour: display colours, progress bar, media preloading, security options, and allowed devices.

14. Default Screens. The screens that frame your trial file: calibration, participant details, fullscreen prompt, and the debrief and redirect at the end.

Collect and read your data

15. How to Read the Results Files. Each session produces a CSV with a header block and one row per trial; this page walks the key columns (response, correct, RT).

16. Results Formats. Choose between individual files, wide, long, and anonymised downloads before you analyse. During collection, the Data & Results dashboard shows live statistics and figures as sessions come in.

For a column-by-column reference of everything Testable writes into these files, use the Results Reference, the results-side companion to the Columns Reference.

You are ready when

You are ready when you can open a blank trial file and write, without looking anything up, an instructions row, a block of scored test rows with stimuli, keys, and timing, and a feedback message, then preview it and say where each response will appear in the results file. Now put it into practice: Create Your First Experiment is the hands-on walkthrough that takes a project from Kickstart form to published, active, and collecting data.