testData Functions

Squish can handle tabular data (rows and columns—or in database terminology, records and fields). With respect to Squish's data handling functions, we use the terms "row" and "record" as synonyms, and similarly, "column" and "field".

Squish can read in test data from .tsv (tab-separated values format), .csv (comma-separated values format), .xls or .xlsx (Microsoft Excel spreadsheet format) files. In the case of .csv and .tsv files, Squish assumes that they use the Unicode UTF-8 encoding—the same encoding used for all test scripts.

The test data functions are used for data-driven and keyword-driven testing. For examples of data-driven testing see the Tutorials, and for examples of keyword-driven testing see How to Do Keyword-Driven Testing.

String testData.create(where, filename)

This function returns the name of a file you can write to. If the where parameter is "shared", the filename will have a path that locates the file in the test suite's shared test data directory (test_suite/shared/testdata/filename), and if the where is "local" the filename will have a path that locates the file in the test suite's, test case's test data directory (test_suite/tst_case/testdata/filename).

This function is designed to be used when you are running a script in a "learning" mode and want to create test data dynamically.

Dataset testData.dataset(filename)

This function (along with the testData.fieldNames, testData.field and testData.datasetExcel functions), is used for data-driven and keyword-driven testing.

The testData.dataset function returns a dataset object that refers to an array or tuple of records. The data is retrieved from the file specified by the filename—providing the data is in one of the file formats that Squish recognizes.

The normal practice is for the filename to be given without a path (e.g., mydata.csv). In this case, Squish first tries to find the file in the test case's data (i.e., in the test case's testdata folder if it has one). If that fails, Squish next tries looking in the test suite's shared data folder (i.e., in the test suite's shared/testdata folder). If the file isn't found (or is found but cannot be read or understood), Squish throws a catchable exception. If the filename is specified with a path (e.g., C:\mydata\mydata.csv), then Squish tries to read that specific file and throws a catchable exception if the file doesn't exist or isn't in a format that Squish can understand.

The field names and field values can be retrieved using the functions described below.

Dataset testData.datasetExcel(filename, sheetname)

This function (along with the testData.fieldNames, testData.field and testData.dataset functions), is used for data-driven and keyword-driven testing.

The testData.datasetExcel function returns a dataset object that refers to an array or tuple of records. The data is retrieved from the file specified by the filename and sheetname — providing the data is in one of the Excel formats i.e., having extension .xls or .xlsx. This function is a specification of the function testData.dataset.

For a detailed description of the function's behavior please see info to testData.dataset above. The only specific is the second parameter of the function, namely sheetname. This is the name of the particular sheet within the Excel document. This parameter is optional. By default the first sheet will be used.

Boolean testData.exists(filename)

This is an old API and it is generally better to use Boolean RemoteSystem.exists(path) instead.

This function returns a true value if a file called filename exists in the AUT's current working directory; otherwise it returns a false value.

String testData.field(record, fieldName)

String testData.field(record, fieldIndex)

This function returns the value of the field specified by the given fieldName string or the given fieldIndex integer, taken from the specified record (i.e., from a particular row from the dataset returned by the testData.dataset function).

See How to Do Data-Driven Testing for usage examples.

SequenceOfStrings testData.fieldNames(record)

This function returns an array or tuple of field names for the specified record (i.e., from a particular row from the dataset returned by the testData.dataset function).

testData.get(filename)

This function copies the file called filename from the AUT's current working directory to squishrunner's current working directory. Generally, for copying remote files to a local machine, it is better to use Boolean RemoteSystem.download(remotePath, localPath) instead.

testData.remove(filename)

This function removes the file called filename from the AUT's current working directory.

testData.put(filename)

If the filename is specified without a path, this function copies the test data file called filename from the test case's directory into the AUT's current working directory. If the filename is specified with a path, this function copies the specified file into the AUT's current working directory. When the AUT is terminated the copied test data file is automatically deleted.

This function returns the full path of the file copied or, in case of error, throws an exception that can be caught in the test script.

Note that if multiple AUTs are involved—for example, if one AUT starts another program—the deletion occurs when the program in whose context the call to the testData.put function was made is terminated.