Run a batch from a CSV

When you need to launch dozens of tests in one go, queuing them one by one is slow. A CSV batch file lets you describe a whole run in a single file: which tests to launch, the variables each one uses, and the options that apply to the batch. Upload it from the run queue and kapptivate executes everything as one batch.

This page is the reference for that file. It describes each section, how to fill it, and how to upload and run it.

The CSV structure

A batch file has three sections, each introduced by its own header line:

__DESCRIPTION__
__OPTIONS__
__TESTS__

__DESCRIPTION__ names the batch and points it at an environment. __OPTIONS__ tunes how the batch runs. __TESTS__ lists the tests to launch. Every value inside a section uses a semicolon (;) as separator.

Description section

The __DESCRIPTION__ section sets the batch name and the variable_group_id of the environment to run against. The batch reads its variables from that group.

__DESCRIPTION__
name;Long Test Suite
variable_group_id;363

Open your product

Go to the product your tests belong to.

Open the variable group

Go to Configurations -> Variables groups and select the group you want the batch to use.

Read the ID from the URL

The number at the end of the URL is your variable_group_id:

https://example.kapptivate.com/customer/project/env/groups/363

Here the ID is 363.

Options section

The __OPTIONS__ section controls how kapptivate executes the batch. Every option is optional, and you can include as many as you need. These map to the same controls as the options of a manual run.

Option	Example value	What it does
`ignore_errors`	`True`	Keep running the batch when a step fails.
`send_result_by_mail`	`True`	Email the results when the batch finishes.
`send_result_by_sms`	`False`	Send the results by SMS.
`send_result_by_call`	`False`	Send the results by call.
`email_recipients`	`john.doe@company.com`	Who receives the email results.
`sms_recipients`	`+33010000000`	Who receives the SMS results.
`call_recipients`	`+33010000000`	Who receives the call results.
`run_later`	`True`	Schedule the batch instead of running it now.
`run_datetime`	`2025-07-27T09:36:54.653Z`	When to run, used with `run_later`.
`timeout_sms`	`30`	Seconds to wait for an SMS.
`timeout_ussd_push`	`30`	Seconds to wait for a USSD push.
`sms_observation_delay`	`0`	Delay before observing an SMS.

__OPTIONS__
ignore_errors;True
send_result_by_mail;True
email_recipients;user@example.com

Tests section

The __TESTS__ section lists the tests to run, one per line. Each line starts with a test ID, optionally followed by key;value pairs that override variables for that test.

TEST_ID;key1;value1;key2;value2

To find a test ID, open the test in kapptivate. The number at the end of the URL is its ID:

https://app.kapptivate.com/.../test/edit/246

The same test can appear on several lines to run it with different variables. Pass as many pairs as you need:

__TESTS__
187;AGENT;R58M92A1MYY
187;AGENT;XPH5T19823002962
190

Line 190 runs the test with no overrides.

Full example

__DESCRIPTION__
name;Long Test Suite
variable_group_id;363

__OPTIONS__
ignore_errors;True
send_result_by_mail;True
email_recipients;john.doe@example.com

__TESTS__
187;AGENT;R58M92A1MYY
187;AGENT;XPH5T19823002962
190

Upload and run

The CSV upload lives in the run queue, next to manual runs and campaigns.

Open the run queue

From the Tests or Executions page, open the run queue from the action button in the bottom right.

Start a CSV upload

In the run queue header, click Upload a CSV file to run batch tests. The Upload CSV to run a tests suite dialog opens.

Select your file

Click or drag your file into the upload area. Only .CSV files are accepted.

Run the tests

Click Run tests. kapptivate redirects you to the batch execution, where you follow it as a multi-test execution.

The upload dialog links to How to create a valid CSV test file, which points to this page. Keep the section headers and the semicolon separator exactly as shown above, or the file is rejected.

Generate it with an AI agent

If your AI assistant is connected to the Kapptivate MCP server, you don't need a CSV at all: it can launch a batch directly from a plain-language request. The CSV route is for assistants that aren't connected, where the agent writes the file and you upload it yourself.

In that case, give it the format from this page as context, then describe your run in plain language.

A simple request:

Build a kapptivate batch CSV for me.
Name it "Nightly smoke" and use variable group 363.
Run tests 187, 190 and 204.
Run test 187 twice: once with AGENT = R58M92A1MYY, once with AGENT = XPH5T19823002962.
Email results to maud@example.com when it finishes, and keep going if a step fails.

A more detailed one, with scheduling and several overrides:

Generate a kapptivate batch CSV.
Name it "Release regression" and use variable group 412.
Schedule it for 2026-06-12 at 09:00 UTC, email results to qa@example.com, and ignore errors.
Run these tests:
- 187 with AGENT = R58M92A1MYY
- 187 with AGENT = XPH5T19823002962
- 190 with no overrides
- 204 with LANG = fr and ENV = staging

Tell the agent to keep the exact section headers (__DESCRIPTION__, __OPTIONS__, __TESTS__) and the semicolon separator. Then save its output as a .csv file and upload it from the run queue.

What's next?

Run a test

Queue tests from the UI, adjust devices and variables, and launch

Run a campaign

Group tests into a campaign and run them as one batch