Generating Questions from Lists

Surveys & forms

Lists let you write one question row and have Testable expand it into a question per item, or feed a whole set of items into a single question’s response options. This keeps your question content separate from the survey structure, so the same list can drive questions, options, and matrix rows.

What is a list?

A list is a named set of items. You can define one by uploading a CSV file in the Files tab, or by initialising it inline in the script column.

Inline definition:

%animals% = ['dog', 'cat', 'bird', 'fish']

You can also build lists dynamically during the experiment, for example by collecting participants’ responses with addToList(). Both inline definition and dynamic building are covered in Scripts.

Displaying list items in a question

Use %listname% in the head or body column to display all items from the list:

head = Please rate each of the following: %animals%

Generating one question per list item

Use #listname# in the head column to automatically generate a separate question row for each item in the list:

head = How much do you like #animals#?

Testable expands this into one question per item at runtime.

Controlling page breaks for generated questions

By default, consecutive form rows collapse onto a single page. When #listname# generates multiple questions, you control how they are paginated with the pageBreak column:

Value	Behaviour
afterAll	All generated questions appear together on one page; the break falls after the last generated question
after (or 1)	Each generated question appears on its own page
before	A page break is inserted before each generated question

Note

afterAll is the only way to break after an expanded list, because all the generated questions come from one spreadsheet row. On a row that is not generated from a list, afterAll produces no break at all.

List items as response options

Use %listname% in responseOptions to turn list items into selectable choices:

responseType    = radio
responseOptions = %animals%

List items as matrix rows

Use %listname% in responseRows to create a matrix question where each list item becomes a row:

head	responseType	responseOptions	responseRows
How important are the following?	radio	not important; neutral; important	%attributes%

Randomising list items

Append .random or .sample(x) to randomise or sub-sample list items:

responseOptions = %animals.random%
responseOptions = %animals.sample(2)%

• .random presents all items in random order
• .sample(x) randomly selects x items from the list

The same suffixes work on #list# wildcards (#animals.random#, #animals.sample(2)#), independently of the listOptions column.

Combining multiple lists: parallel and nested

By default, multiple #list# wildcards in the same row loop in parallel: one item from each list per generated question, advancing together. Use the listOptions column to switch to nested looping, where every combination is generated:

head	listOptions
What do you think about #animals# and #traits#?	nested
What do you think about #animals# and #traits#?	nested(animals, traits)
What do you think about #animals# and #traits#?	parallel

• nested generates every combination of items across all the row’s lists
• nested(list1, list2) is the same, but only over the named lists; unlisted lists run in parallel
• parallel is the default; lists advance together one item at a time, and shorter lists pad with empty values

What the results record

The item each generated question actually used is recorded per column as <column>_actual in the results file.

Next steps

• Forms and Surveys: the survey question types lists can feed
• Generating Trials from Stimulus Lists: the experiment-side counterpart, generating trials from uploaded lists
• Scripts: define lists inline or build them from responses during the experiment