DataTables can be associated with both new and existing tests.

It is important to note that DataTables are associated on the test level. If a plan includes a test that uses a DataTable, by default, the plan will run all associated DataTables. You can change this behavior by modifying individual plans. And if such a test is in a plan stage that runs sequentially, the tests will run one at a time in order through the DataTable scenarios.

How to associate a new test with an existing DataTable

1. Create a new test from either the main dashboard page via the "New" button, or from the "Tests" page in the sidebar.
2. Toggle "Show advanced options" on and scroll to the "DataTables" section.
3. Choose one or more DataTables from the list of existing DataTables. (By default, the test will run each scenario from each table.)

📘

Train with DataTable

We recommend making sure the "train with DataTable" button is selected so you can instantly use one of the above DataTables to train.

4. Select the specific DataTable you'd like to train with using the "DataTable for training..." dropdown. (If you'd like to add any advanced options, such as adding a login flow, do so now.)
5. Click the "Create test" button to start training.

6. While training, you can view or manage the data-driven variables from the variables menu at the bottom of the Trainer. Tests train with the first scenario from a DataTable.
7. Save the test. Your test will now run in every plan it's in with the associated DataTables.

🚧

Important information about associating DataTables

When you associate a DataTable with a test, all instances of that test will automatically run using that DataTable for all future runs.

If you wish to run a test within a specific plan without a certain DataTable, you can choose to ignore DataTables in the plan stage settings.

How to associate existing tests and DataTables

1. Navigate to the test you wish to associate with a DataTable
2. Click on the "Update Info" button.
3. In the modal, select a DataTable for the test in the "DataTables" dropdown.

4. Click the save button in the bottom of the modal, and you're all done!

📘

Associating Multiple DataTables

If you associate multiple DataTables with a single test, while training, you will only see the variables and default values from the first scenario of the first DataTable associated.

You can reference the variables from other related DataTables by going to Variables>Manage and adding them there. For example, consider a scenario with DataTables 1 and 2. DataTable 1 has variables A and B, and DataTable 2 has variables C and D. By default, you will only see variables A and B during training. To add variables C and D, go to Variables>Manage and define the default values there.

🚧

LIMITATION

In a local run, the test will use the variable values for the first scenario. Running all DataTable scenarios in local runs is not supported.

How to prevent an associated DataTable from running for a specific plan

1. To prevent a test from using a DataTable for a specific plan, edit the plan's settings.
2. Find the specific test in the Tests section.
3. Click the pencil icon to open up the options panel.

4. Click "Add parameter". To prevent the test from using any associated DataTable, set the Type field to "Ignore DataTables".

5. If the test is associated with multiple DataTables, you can also force the test to run with a specific DataTable. To do so, set the "Type" field to "DataTable" and set the "DataTable" field to the specific DataTable you wish to use for this plan run.

🚧

Notice the number of test runs

A plan will run a test once for each row in the associated data tables, or once for each test without a data table (as before), multiplied by the number of browsers configured.

Ex: Suppose there is a plan configured to run on Chrome and Firefox with 3 tests, one with no data table, one with a data table with seven rows, and one with a data table with eleven rows. It will execute 2 (1 + 7 + 11) = 2 19 = 38 test runs each time the plan runs.

📘

Data tables and default values

The default values assigned to the data-driven variables have a hierarchy. If the data-driven variable in a given test has a default value assigned to it that is different than the first scenario of the data table associated with it, it will automatically update to that scenario's value upon editing the test.