Manage and assign data sources | Ranorex Studio User Guide
Help CenterUser GuideRanorex Studio advanced

Manage and assign data sources

Data sources are a key component of data-driven tests. They are the place from which variables get their values. In this chapter, we’ll find out how to add, manage and assign data sources to test containers so that their data is available for the test run.

In this chapter

    tipp icon

    Screencast

    The screencast “managing data sources” walks you through the information found in this chapter.:

    Watch the screencast now

    Create your data source

    Creating a data source is as easy as creating a table. How exactly your data source will look depends on your tests, so making recommendations on how to design your data source is beyond the scope of this user guide.

    To follow along with our sample solution, you’ll need a data source.

    Download the CSV table and unzip it to any directory on your computer or simply copy and paste the following text into a text file and save it as .csv.

    FirstName,LastName,Age,Gender,Department,Num
    John,Public,48,Male,Project Management,1
    Mary,Smith,36,Female,Sales,2
    Henry,Rogers,29,Male,Support,3
    Thomas,Bach,42,Male,Development,4
    Cindy,Martens,19,Female,Office,5
    Hanna,Perry,48,Female,Management,6
    Will,Hallmark,32,Male,Support,7
    Nicole,Wallace,38,Female,Testing,8

    Manage data sources

    Data sources, and the test data they contain, are managed per test suite. This means:

    • Once added to a test suite, the data source can be assigned to the test containers of this test suite.
    • You can’t access a data source in test suite A from test suite B. You first need to add the data source to test suite B.
    • A data source can be used in multiple test suites at the same time if you add it to each test suite.

    To access data source management directly:

    Click MANAGE DATA SOURCES… in the test suite view.

    You can also access data source management through the Data source… dialog. With a test container selected:

    Click Data source… in the test suite toolbar and then Manage data sources…
    Click Data source… in the context menu of a test container and then Manage data sources…

    Accessing test data management

    The data source management dialog

    The data source management dialog appears as shown below. To add the CSV data source for our sample project:

    Click New > CSV connector…

    Basic data source operations

    Add a new data source. Four different types are available, as explained below.

    Delete an existing data source.

    tipp icon

    Attention

    Deleting a simple data table means deleting the data physically. Data will be lost! This is because simple data tables are stored directly in the corresponding test suite file.

    Deleting an Excel, CSV, or SQL data source in this dialog means deleting only the connector to this data source and the settings in the Configuration section, not the data source file itself.

    Clone a data source.
    For simple data sources, this means cloning the contents of the data source and the settings in the Configuration section. For all other data sources, this means cloning the connector and the settings in the Configuration section. This option is useful for specifying different sheets of the same Excel data source, for example.

    List of added data sources, each showing the connector type (Simple, CSV, Excel, SQL) and the Use count (how many times the data source has been assigned in the test suite).

    Configuration section. Here you can manage certain settings depending on the data source type. The available settings are explained below for each data source type.

    Assign data sources

    Once you’ve added a data source, you then need to assign it to a test container, so the modules/variables in it can access the data.

    To do so:

    Select the test container you want to assign a data source to.
    Open the context menu and click Data source…

    Accessing test data assignment from test case and smart folder

    Select the desired data source from the drop-down menu and click OK.
    The data source appears next to the test container in the test suite view, with the number of rows in it indicated.

    Assigning a data source to a test case or smart folder

    Data source assignment rules

    The assignment of data sources to test containers is subject to the following three rules:

    Rule 1 Once assigned to a test container, a data source cannot be assigned to descendants of this test container.
    Rule 2 Once assigned to a test container, the contents of the data source can be accessed by all descendants of this test container, but not by its siblings or ancestors.
    Rule 3 Multiple assigned data sources in a tree complement each other; they do not replace each other.

    Example 1

    Let’s see how these rules work by way of an example. Suppose we have two data sources available in a test suite: a CSV data source, myCSVData, and an Excel data source, myExcelData.

    Data source assignment example I

    The CSV data source is assigned to the smart folder A-1.
    The Excel data source is assigned to the smart folder A-2.
    Because of rule 2, test case A and its module cannot access the data sources of the descendant test containers.
    Because of rule 2, modules of the smart folder A-1 have access to the CSV data source.
    Because of rules 2 and 3, all modules of the smart folder A-2 have access to both the CSV and Excel data sources.
    Because of rules 2 and 3, all modules in descendants of the smart folder A-2 have access to both the CSV and Excel data sources.

    Example 2

    Data source assignment example II

    All data sources have been assigned below test case B and smart folder 1. Therefore, these test containers and their modules cannot access the data sources.

    The Excel data source is assigned to the smart folder 1-1. Therefore, the descendants (modules, test containers) of this tree branch can access the Excel data source.

    The CSV data source is assigned to the smart folder 1-2. Therefore, its modules can access this data source.

    The Excel data source is assigned to smart folder 1-2-1. Therefore, its descendants can access both the CSV and the Excel data sources.

    The Excel data source is also assigned to smart folder 1-3-1. Therefore, its descendants can access this data source.

    Data source types and connectors

    Ranorex Studio supports four different types of data sources: Simple, CSV, Excel, and SQL data tables.

    With the exception of simple data tables, all of these sources are added via connectors. This means that Ranorex Studio only links to the data table file. It does not add the contents of the file to the test suite.

    Simple data table


    Simple data tables are useful for when you want to quickly set up small data-driven tests, e.g. for trial and error. We do not recommend them for anything that’s more complex than a couple of data rows.

    Simple data tables are stored directly in the test suite file (.rxtst), with all of their contents. This is why you have to create and maintain them directly in the Data source… dialog. It’s also why they are deleted entirely when you delete them in the data source management dialog, unlike other data sources.

    To add a new simple data table:

    Click New > Simple data table.
    Name the data source.
    Click OK.

    Creating a simple data table - part I

    The Mask option is explained separately further below.

    The Label option is explained separately further below.

    In the Data source… dialog of a test container, select the simple data source and create the content in the table editor.

    tipp icon

    Hint

    You can paste tables from Excel files into the table editor.

    Creating a simple data table - part II

    Click OK when you’re done.

    Creating a simple data table - part III

    You can also specify a data range. This option is explained separately further below.

    Excel data connector


    Excel data sources are added via a connector.

    tipp icon

    Hint

    Instead of the default Excel file format xlsx, you can also use the native binary file format xlsb. This file format is supported in Microsoft Office 2007 and later, and is much faster than the non-binary version.

    To add an Excel connector:

    Click New > Excel connector…
    Configure the connector and click OK.

    Creating an Excel data connector

    Excel connector configuration:

    Name the Excel connector and specify the location of the Excel file.
    This will copy the Excel file to your project folder. You must check this if you use version control.

    tipp icon

    Hint

    We strongly recommend checking this option in any case. This way, you won’t have to worry about where your test data file is located. Also, when you deploy your test, e.g. via Ranorex Remote, the file will be transferred to the Ranorex Agent in the runtime environment automatically.

    Work sheet selection

    If your Excel file contains more than one worksheet, you can specify the sheet to be used here. You can also limit the test data to a specific range.

    Uncheck the auto-load option to decrease the start-up loading time for the test suite. However, this also means the number of rows won’t be displayed next to test containers.

    tipp icon

    Hint

    Use the Clone option to quickly create multiple Excel connectors that link to the same file, but different worksheets or ranges.

    The Mask option is explained separately further below.

    The Label option is explained separately further below.

    CSV data connector


    CSV data sources are added via a connector. Once added, CSV data sources can be edited in Ranorex Studio in the Data source… dialog. When you save these changes by clicking OK or Apply, the actual CSV file will also be changed.

    To add a CSV connector:

    Click New > CSV connector…
    Configure the connector and click OK.

    Creating a CSV data connector

    CSV connector configuration:

    Name the CSV connector and specify the location of the CSV file.
    This will copy the Excel file to your project folder. You must check this if you use version control.

    Data configuration

    Specify whether the CSV file contains a header row or not.

    Uncheck the auto-load option to decrease the start-up loading time for the test suite. However, this also means the number of rows won’t be displayed next to test containers.

    The Mask option is explained separately further below.

    The Label option is explained separately further below.

    SQL data connector


    With the SQL data connector, you can access an SQL database and pull data from it using an SQL query. We’ll illustrate this process with a simple example where we access a Microsoft Access database.

    Click New > SQL connector…
    Name the connector.
    Click Create to specify the SQL connection string.

    Creating an SQL data connector - part I

    Specify the location of the database file.
    Specify the optional connection settings (see below) and click OK.

    Optional connection settings:

    Change the database connection type to suit your database type. In our example, Microsoft Access Database File is correct, since we’re using a Microsoft Access database.
    If the database requires a login, specify it here.
    Click to test the connection to the database (recommended).

    Creating an SQL data connector - part II

    Under Query, click Create to specify the database query.

    Creating an SQL data connector - part III

    Define the desired SQL query in your database (Microsoft Access, in our example) to provide the data to Ranorex Studio and click OK.

    SQL database query designer

    Set the auto-load behavior (disable for faster load time, but missing row indicators in the test suite view) and masking (explained separately below) and click OK.

    Creating an SQL data connector - part IV

    Mask data

    You can mask data for all data source types. This way, you can hide sensitive data in the report while still allowing Ranorex Studio access to it for testing purposes.

    Masking data in report

    Data from unmasked columns is displayed normally in the report.
    Data from masked columns is hidden in the report.

    Label data iterations

    By default, data iterations carried out as part of a data-driven tests use the iteration count as a label in the report, i.e. they are numbered. However, you can also assign column names from your data source as labels. Ranorex Studio will then use the values in that column as labels in the report.

    Masking data in report

    Default iteration count with numbers from 1 to 18 in the report.
    Data-source column LastName selected as the label instead.
    The iterations now use the respective values of the column LastName as label, making them easier to identify.

    Limit data range

    You can limit the data range for all data sources. This allows you to make only certain rows of a data source available to a test container.

    Enter a range of rows in the Data source… dialog.
    Click Preview effective data set… to see the result.

    Selecting a data range

    Auto-create a CSV data source from variables

    You can automatically create a CSV data source from unbound variables defined in modules.

    The test suite shown below contains the smart folder InsertData, which in turn contains four recording modules with 5 defined, but unbound variables.

    Smart folder InsertData with four recording modules.

    The 5 defined, but unbound module variables in the recording modules.

    To auto-create a CSV data source from these variables:

    Right-click the smart folder.

    Click either Data source… or Data binding….

    Click Auto-generate data source.

    Result

    Ranorex Studio automatically creates a CSV data source with the variable names as the column names.

    Auto-generated CSV data source with the default name derived from the test container.

    Table with the column names derived from the varible names.

    Ranorex Studio also automatically binds the variables to the matching columns in the auto-created data source, visible under Data binding.

    You can manage the data source as usual in the Manage data sources… dialog. By default, the CSV file is stored in the project folder of your solution.

    Auto-generated CSV data source in the Manage data sources… dialog.

    The CSV file in the project folder of your solution.

    Summary of the steps for this chapter

    Now that we’ve explained all the options for managing and assigning data sources, let’s quickly go through the required steps to prepare our sample solution for the next chapter again.

    Ensure you have your data source ready (CSV file).

    In the test suite view, click MANAGE DATA SOURCES….

    Click New > CSV connector…

    Name it myCSVData, specify the location of the file, check all three boxes, and click OK.

    In the test suite view, right-click the test case Data-driven_DB_Test and click Data source…

    From the drop-down menu, select myCSVData and click OK.

    You’ve now assigned the data source. Your solution is ready for the next step: data binding.