Enabling a test to use a dataset

Before a test can use variable data from a dataset, you must update the test to include a reference to that dataset.

Procedure

In the Test Navigator, browse to the test and double-click it. The test opens.
Right-click the test name, and click Add > Dataset.
The Select Dataset File window is displayed listing the datasets available to the test. If a test is already using a dataset, it does not appear in the list.
In the Existing Dataset in workspace list, click the name of the dataset that your test will use and click Next.

Select the Open mode for the dataset. This mode determines the view that virtual users have of the dataset. This option is useful when you do a parallel test run.

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	Virtual users draw 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. However, 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 in a loop with more than one iteration.
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

Virtual users draw 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. However, 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 in a loop with more than one iteration.

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.

Select the Access mode for the dataset:
- 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 whether the test will reuse data when it reaches the end of the dataset.
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 check box Wrap when the last row is reached. 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 as Fail because of the forced stop, the performance data in the test is still valid. However, if it does not matter to your application if data is reused, 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.
Select whether the test will make the data in the dataset record permanent for each virtual user.

By default, one row is retrieved from the dataset for each execution of a 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 two 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.
A reference to the dataset is added to the test, and the Test Details area is updated with the dataset information.
Save the test.

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

What to do next

Now that you have created a reference between the test and the dataset, the next step is to associate a value in the test with a column in the dataset.