Using Parameters

LegiTest ›› Tutorials ››
Parent Previous Next

Using Parameters

LegiTest includes the ability to parameterize a test suite. Test suite properties can use the parameters to allow easy porting between environments. This tutorial uses the Pragmatic Works HigherEd demonstration project. The test suite tests an SSIS package ensuring it extracts and then loads data into a data warehouse. By the end of this tutorial the test suite will use parameters to allow for easier deployment.

Users unfamiliar with LegiTest's layout should first familiarize themselves with the tutorial overview. Users already familiar with the LegiTest layout can continue to the following parameter tutorials:

Table of Contents

  Test Suite Parameter Tutorial

o   Direct Property Replacement

o   Parameter Token Replacement

o   Environment Token Replacement

  legiTestSettings Files

  Global Parameters


Within the test suite, select the "Parameters" node to view parameter settings. This area allows user to create and manage test suite parameters. We'll be revisiting this area shortly, for now let's look at the remaining pieces of the test.

Figure 1

If you select the "HigherEdETL" node, the view will change test suite level elements. Test suite level assets are available for use across all groups and tests. This test suite contains three assets:

  HigherEd: A Connection asset referencing the HigherEd database

  HigherEdDW: A Connection asset referencing the HigherEdDW database

  SSIS Catalog: A Connection asset referencing the SSIS Catalog that stores the package

Figure 2

As of now, the HigherEdDW connection references our local data source. This will later be overridden with a parameter for easier deployment.

Figure 3

If you select the "HigherEdETL_Dim_Doner" node, the view will display group elements. Click here more information on a test group's test flow. Group level elements are only available for the specific group and its tests. This group contains a single asset:

  Dim_Donor: An SSIS Package Reference that references the SSIS package

Figure 4

Selecting the "HigherEdETL_Dim_Donor_DataCompare" node displays test elements.

Important Note:

Usually, test suites contain more than one test. This test suite has minimal complexity to better illustrate the use of parameters.

The "HigherEdETL_Dim_Donor_DataCompare" contains five main areas, though this test uses only four.

Figure 5

   Test Assets: Assets used by all elements within this test.

o   DimDonor Manifest: A Comparison Manifest that describes how to compare the Donor and Dim_Donor table

o   HigherEdDW Dim_Donor Grid: The Query Asset containing a T-SQL query that extracts the Dim_Donor table

o   HigherEd Donor Grid: The Query Asset containing a T-SQL query that extracts the Donor table

  Test Initialization Steps: These elements run before all execution tracks.

o   Load Dim_Donor: A Load Package action that loads the Dim_Donor package. LegiTest needs to load an SSIS Package before it can run within the execution track

  Execution Tracks: Each execution track runs asynchronously. Within a single execution track the actions run from left to right. This particular test contains only a single execution track.

o   Execute Dim_Donor:  An Execute Package action that executes the Dim_Donor package

o   Load HigherEdDW Dim_Donor (Grid): The Execute Query (Grid) loads the Dim_Donor table for comparison

o   Load HigherEd Donor (Grid): The Execute Query (Grid) loads the Donor table for comparison

  Test Teardown Steps: Elements within this area execute after all execution tracks. This sample test contains no elements within this area.

  Asserts: These elements determine whether the test passes or fails.

o   Grid Comparison: A Grid Comparison assert that compares whether Dim_Donor and  Donor are identical

Test Suite Parameter Tutorial

As created, the test contains hard-coded package and connection references. Rather than using hard-coded references, parameters allow for flexible deployment across environments. This tutorial walks through the process of configuring the connections to reference parameters.

1.  From the test suite's parameter area, click the Parameters' "Add" button

Figure 6

Important Note:

Test Suites can use parameters in one of two replacement methods.

  Direct Property Replacement: Users can map a parameter to a property within the test suite

  Parameter Token Replacement: Users can insert tokens within a property value. When using this method, LegiTest interprets these as a parameter.


  Environment Variable Replacement: Users can insert system environment variables within a property value. When using this method, LegiTest interprets these as environment variables.


At test execution, LegiTest replaces all parameters with the supplied value. This parameter replacement occurs regardless of the method used. This tutorial provides examples of both ways.

2.   Create the following parameters:

Parameter Name








Data Source=localhost;Initial Catalog=HigherEdDWTesting;Integrated Security=True




Figure 7

Direct Property Replacement

Users can map parameters to properties within the LegiTest's Parameter area. This is the most basic form of parameter mapping. Direct property replacement completely replaces the entire property value with the value specified.

1.   From the test suite's parameter area, click the Parameter Mappings' "Add" button

Figure 8

2.   The next window displays an organized list of all available element properties. Navigate to the HigherEdDW connection asset and select its ConnectionString property.

3.   Within the parameter drop down list, select the HigherEdDW_ConnectionString parameter

Figure 9

4. Click "Ok"

Parameter Token Replacement

Using parameter token replacement, users can replace portions of a property. This allows users to replace pieces of a property instead of the entire property. When using this method, LegiTest interprets these as a parameter.


All actions that rely on the HigherEdDW asset now use the HigherEdDW_ConnectionString parameter. The Dim_Donor package still contains connection managers pointing to the original database. The package's connection managers need parameter mappings as well.

1.   Within SSDT or BIDS, select each of the connection managers and view its properties.

2.   Copy out the connection's connection string property. This connection string property will form the baseline for the parameter token replacement. Do this for both connection strings.

Figure 9

Below are the original values for the connection strings.

Connection String



Data Source=localhost,1433;Initial Catalog=HigherEdDW;Integrated Security=True;Application Name=SSIS-InvalidPackage-{C15B09F5-6159-4B38-A44F-69C9A98C8612}localhost,1433.HigherEdDW;


Data Source=localhost,1433;Initial Catalog=HigherEd;Provider=SQLNCLI11.1;Integrated Security=SSPI;Auto Translate=False;

3.   Back within LegiTest, select the HigherEdETL_Dim_Donor_DataCompare node.

4.   Add a Set Property action within the Group Initialization steps.

Figure 10

5.   Replace the Data Source and Initial Catalog within the connection strings. Below, with emphasis, are the replaced values for the connection strings.

Connection String



Data Source={{DataSource}},1433;Initial Catalog={{InitialCatalog}};Integrated Security=True;Application Name=SSIS-InvalidPackage-{C15B09F5-6159-4B38-A44F-69C9A98C8612}localhost,1433.HigherEdDW;


Data Source={{DataSource}};Initial Catalog={{InitialCatalog}};Provider=SQLNCLI11.1;Integrated Security=SSPI;Auto Translate=False;

6.   Select both Connections and replace the ConnectionString with their modified value

Figure 11

7.  There should be two ConnectionString property values that were changed. Once for HigherEdDW_ADO and again for HigherEdDW_OLEDB.

Figure 12

Environment Token Replacement

Using environment token replacement, users can use system environment variables to replace portions of a property. This allows users to replace pieces of a property instead of the entire property. When using this method, LegiTest interprets these as a parameter.


The steps to using environment token replacement are identical to parameter token replacement.

legitestSettings Files

The previous tutorial explained how to use parameters within Visual Studio.  Within the MSTest and nUnit command line LegiTest can use setting files. These setting files control parameters during runtime. LegiTest even generates the file for you when building the project. This parameters file is located within the test suite's output folder.

Figure 13

1.   When a test runs, LegiTest looks in the following locations for setting files:

o   User Profile: %USERPROFILE%\Documents\PragmaticWorks\LegiTest


o   Program Data: %PROGRAMDATA%\PragmaticWorks\LegiTest


Important Note:

Pragmatic Works recommends using the Program Data location to store legitestSettings files. These directories can hold many *.legitestSettings files, the file names are not important. LegiTest only searches for files with the *.legitestSettings extension. We recommend renaming setting files after the tests they belong to.

LegiTest searches the folders in the above order. If duplicate parameters exist in both locations, LegiTest uses the Program Data mapping. Within the same location, LegiTest applies parameters in alphanumeric order.

2.   Below is sample content of the settings file from the above tutorial:

<?xml version="1.0" encoding="utf-8" ?>

<ParameterSet applicableTestSuiteId="a3856bd9-e9fe-460e-bf83-5104eff9458a">


<Parameter name="HigherEdDW_ConnectionString" type="System.String" value="Data Source=localhost;Initial Catalog=HigherEdDWTesting;Integrated Security=True" />

<Parameter name="DataSource" type="System.String" value="localhost" />

<Parameter name="InitialCatalog" type="System.String" value="HigherEdDWTesting" />



<Mapping parameterName="HigherEdDW_ConnectionString" targetElementId="bea91e70-8d45-480f-8c63-f568388cf8dd" targetPropertyName="ConnectionString" />



1.   applicableTestSuiteId: Associates the collection of parameters and mappings with all test suite's of the specific identifier. Only test suites with the corresponding id will use this setting file.

Important Note:

Global Parameters are parameters within a settings file that don't include an applicableTestSuiteId. In such a scenario, all test suites executed on that machine would use those global parameters. More details regarding the usage of global LegiTest Setting files and parameters can be found here.

2.   targetElementId: Associates a parameter value to a specific element within the test suite using the element's unique identifier. The targetPropertyName attribute reference's the specific property that the parameter value will replace.

In this tutorial, We parameterized only the connection strings of a test suite. LegiTest can use parameters throughout all its actions, asserts, and assets. The query strings for a Query asset is another good example where parameters would be useful.

Through the use of parameters, users can transition between many environments. Parameters help keep the testing process flowing through the various stages of development.