Creating datasets with multiple substitutions

Earlier to 9.2, you could substitute one dataset value at a time. Starting from 9.2, after the test is generated, you can view all the dataset candidates, add multiple candidates as dataset values, substitute values, and create a new dataset out of it. You can also substitute multiple dataset candidates for an existing dataset.

When you substitute multiple dataset candidates to create a new dataset, the same number of columns are created in the dataset. The names of the candidates become the names of columns and values in the dataset. When you substitute multiple dataset candidates in an existing dataset, the column names in the dataset are retained. If the number of substitutions chosen was greater than the number of columns in the dataset, the extra number of substitutions are added as columns in the dataset. For instance, if a dataset has three columns and you substitute five dataset candidates, two new columns are created by using the names of the dataset candidates.

To create a dataset from multiple dataset candidates:

In the Test Editor, select the name of the test and from the Test Details section, select Common Options and click Show Dataset Candidates.
Alternative: After the test generation when you open the test, you are prompted that Some test data may need to be correlated or substituted. If you click Yes, you can see the list of dataset candidates.
Select the dataset candidates that you want to add as values to the dataset and click Substitute multiple candidates.
The Add Dataset dialog shows the list of datasets that are in the project but not associated with the test.
To associate an existing dataset with the test and assign the selected dataset candidates as values and substitutions, select a dataset and click Next. To associate a new dataset with the test, click the Use wizard to create new Dataset and click Next.

Select Open mode for the dataset. This mode determines the view that virtual users have of the dataset.

Different tests can open the same dataset differently, and you can change the open mode later by opening the test and double-clicking the dataset title.

Option	Description
Shared (per test execution) (default)	When you choose the Shared (per test execution) option, the virtual users running in the test share the dataset values in sequential order. For example, if your dataset has 10 rows, the dataset values are taken from row 1, row 2, row 3, and so on when you select this option.
Private	Each virtual user draws dataset values from a private view of the dataset, with dataset rows apportioned to each user in sequential order. This option ensures that each virtual user gets the same data from the dataset in the same order. Because each user starts with the first row of the dataset and accesses the rows in order, different virtual users will use the same row. The next row of the dataset is used only if you add the test that is using the dataset to a loop in the schedule with multiple iterations.
Shared (for all test executions)	When you choose the Shared (for all test executions) option, the virtual users running in multiple tests share the dataset values from the current row. For example, if your dataset has 10 rows and when you set the current row as row 5, the dataset values are taken from row 5 instead of row 1 when you select this option. If you had set the current row as row 1 and used the dataset values until row 5, the dataset values are retrieved from row 6 when you run the test next time.

Option

Description

Shared (per test execution) (default)

When you choose the Shared (per test execution) option, the virtual users running in the test share the dataset values in sequential order.

For example, if your dataset has 10 rows, the dataset values are taken from row 1, row 2, row 3, and so on when you select this option.

Private

Each virtual user draws dataset values from a private view of the dataset, with dataset rows apportioned to each user in sequential order.

This option ensures that each virtual user gets the same data from the dataset in the same order. Because each user starts with the first row of the dataset and accesses the rows in order, different virtual users will use the same row. The next row of the dataset is used only if you add the test that is using the dataset to a loop in the schedule with multiple iterations.

Shared (for all test executions)

When you choose the Shared (for all test executions) option, the virtual users running in multiple tests share the dataset values from the current row.

For example, if your dataset has 10 rows and when you set the current row as row 5, the dataset values are taken from row 5 instead of row 1 when you select this option. If you had set the current row as row 1 and used the dataset values until row 5, the dataset values are retrieved from row 6 when you run the test next time.

If you are setting how the test accesses the dataset during this session, select one of the following options:
- Sequential: Rows in the dataset are accessed in the order in which they are physically stored in the dataset file, beginning with the first row and ending with the last.
- Random: Rows in the dataset are accessed in any order, and any given row can be accessed multiple times or not at all. Each row has an equal chance of being selected each time.
- Shuffled: Before each dataset access, the order of the rows is changed that results in a different sequence. The rows are accessed randomly but all rows must be selected once before a row is selected again.

Select one of the following options.

Option	Description
Wrap when the last row is reached	By default, when a test reaches the end of a dataset or dataset segment, it reuses the data from the beginning. To force a test to stop at the end of a dataset or segment, clear the Wrap when the last row is reached check box. Forcing a stop might be useful if, for example, a dataset contains 15 records, you run a test with 20 virtual users, and you do not want the last five users to reuse information. Although the test is marked Fail because of the forced stop, the performance data in the test is still valid. However, if reusing dataset data does not matter to your application, the default of wrapping is more convenient. With wrapping, you need not ensure that your dataset is large enough when you change the workload by adding more users or increasing the iteration count in a loop. Note: With Random access order, Wrap when the last row is reached option is unavailable because you never reach the end of the row. With Shuffled access order, if you select Wrap when the last row is reached option, you resume selecting from the beginning of the row with the same access order after each row has been selected once. No more selections are required if you clear the Wrap when the last row is reached option.
Fetch only once per user	By default, one row is retrieved from the dataset for executing each test, and the data in the dataset row is available to the test only for the duration of the test. Select Fetch only once per user to specify that every access of the dataset from any test being run by a particular virtual user will always return the same row.

Option

Description

Wrap when the last row is reached

By default, when a test reaches the end of a dataset or dataset segment, it reuses the data from the beginning. To force a test to stop at the end of a dataset or segment, clear the Wrap when the last row is reached check box. Forcing a stop might be useful if, for example, a dataset contains 15 records, you run a test with 20 virtual users, and you do not want the last five users to reuse information. Although the test is marked Fail because of the forced stop, the performance data in the test is still valid. However, if reusing dataset data does not matter to your application, the default of wrapping is more convenient. With wrapping, you need not ensure that your dataset is large enough when you change the workload by adding more users or increasing the iteration count in a loop.

Note:

With Random access order, Wrap when the last row is reached option is unavailable because you never reach the end of the row.
With Shuffled access order, if you select Wrap when the last row is reached option, you resume selecting from the beginning of the row with the same access order after each row has been selected once. No more selections are required if you clear the Wrap when the last row is reached option.

Fetch only once per user

By default, one row is retrieved from the dataset for executing each test, and the data in the dataset row is available to the test only for the duration of the test. Select Fetch only once per user to specify that every access of the dataset from any test being run by a particular virtual user will always return the same row.

To illustrate how these options affect the rows that are returned, assume that a test contains a loop which accesses a dataset. The loop has 2 iterations. The following table shows the row that is accessed in each iteration:

Dataset option	Iteration 1	Iteration 2
Sequential and Private	row 1	row 2
Shared and Shuffled	row x	row y
Fetch only once per user	row x	row x

Click Finish.