Keep this beside your editor

Use this as a map when you know what you want to change but do not yet know where to look. You do not need to memorize the API.

From a question to a program

Write five sentences before adding features:

The participant sees ….
They respond by …, before ….
The critical difference between conditions is ….
One task row must contain ….
I will know this works when … happens in a deliberate test.

In the course folder, index.html loads libraries and scripts; stimuli.js or items.js holds the item list; app.js defines the task. In a small lab, setup is supplied around the editable snippet. Downloaded lab JS includes that setup, and the small-example ZIP includes HTML and libraries.

Find the right place to edit

I want to change…	Look here	Check afterward
Words, pictures, condition labels	Item list	Item IDs remain unique; counts still match the design
What appears in one trial	`stimulus` or `prompt`	The visible item agrees with its saved fields
Accepted response keys	`choices`	Instructions and expected keys agree
Maximum response time	`trial_duration` in milliseconds	A deliberate timeout gives null response/RT
Order of different phases	The array passed to `jsPsych.run`	Instructions, practice, and test occur in the intended order
Order of items within a phase	`randomize_order` on the procedure	Counts stay the same; only order changes
Data known before a response	`data` fields / item list	Saved labels identify item, task, block, and condition
Correctness after a response	`on_finish`	Correct, wrong, and omitted responses score as intended
Whether to repeat practice	`loop_function`	Current-attempt criterion and attempt maximum both apply
Whether test is allowed	`conditional_function`	Failed practice produces no test rows

Four distinctions that prevent many bugs

Building versus running. An ordinary JavaScript loop can build a timeline before any trial starts. A jsPsych timeline loop repeats a procedure while the experiment runs. Choose the tool that matches the required behavior.

Placeholder versus current value (Meeting 2). Use jsPsych.timelineVariable("text") directly as a parameter. Inside a JavaScript function or a template string built by that function, use jsPsych.evaluateTimelineVariable("text") to obtain the current value.

Expected versus observed response. An expected key is part of the design. response is what actually happened. Validate an answer key against the stimulus and mapping, independently of the key itself.

Completion versus saving. A final screen does not prove that a result was stored. For local work, download and reopen a file. For JATOS or Cognition.run, retrieve the completed result from that runner.

Read one row before summarizing many

This abbreviated row is illustrative, not a participant result:

{
  "task": "stroop",
  "block": "test",
  "item_id": "i1",
  "condition": "incongruent",
  "word": "BLUE",
  "ink_color": "red",
  "correct_response": "f",
  "response": "j",
  "rt": 640,
  "correct": false,
  "omission": false
}

Under F = red, G = blue, H = green, J = black, the expected response is F. This is an incorrect response, not an omission. It contributes one incorrect trial to accuracy and does not enter the mean correct-response RT. If it timed out instead, response and RT would both be null, and omission would be true.

Saved value	What it means
Keyboard `response: "f"`	An allowed key was pressed
Button `response: 0`	The first choice was clicked, regardless of its label
`response: null`, `rt: null`	No allowed response before the trial ended
A field is absent	That trial did not record that field; inspect its task/plugin
An empty movement array	No events of the tracked kind were recorded; check the task and interaction
`correct_response`	The programmed key/index, which still needs an independent check

Filter, then calculate

First choose the task and block. For course accuracy, use correct task responses divided by all task trials, including omissions. For mean correct RT, use only correct responses with finite RT. An empty eligible RT subset has no mean: store null and display N/A. Do not replace missing RT with zero.

The worked data audit and Meeting 2 practice provide a small calculation you can verify by hand.

A five-case pilot

Run a normal response, an incorrect response, an omission, a relevant loading/control-flow failure, and a complete save/retrieval. Record the expected outcome, observation, evidence, fix, and retest. Use the pilot log. A bug found and explained is more useful than an undocumented “everything worked.”

For a specific symptom, use the debugging checklist. For the complete assessed work, follow the assignment briefs.