Get Help

Yaml@1

Yaml@1 reads a list out of a YAML file — test data, or definitions of tests, queries and data sources. Nothing to install.

Connects to

YAML files — the project file among them. Yaml@1 is the provider behind the implicit list: every definition written under Data sources:, Queries: or Tests: in the project file is read by this provider, exactly as definitions in a separate YAML file would be. Its primary purpose is loading definitions; testing data in YAML files is the second use.

Example

A YAML file with data to test, registered as a data source with the friendly name DepartmentData:

Name
DepartmentData
Technology
YAML
Provider
Yaml@1
Connection string
./DepartmentData.yaml
Data sources:
- Name: DepartmentData
  Provider: Yaml@1
  Technology: Yaml
  Connection string: ./DepartmentData.yaml

A test against it names the node to read in Query:

Tests:
- Name: Check number of generated records
  Data source: DepartmentData
  Query: /Departments # path to the list, with slashes
  Expectation: set row count
  Expected row count: 10

Test definitions

Tests and data sources can be defined in the project file alone. As the project file grows, it can be split: CAT then loads tests from other YAML files through Yaml@1.

Get list of tests from:
- Provider: Yaml@1
  Name: Smoke tests # a list's name is optional, useful for troubleshooting
  Connection string: ./SmokeTests.yaml # relative paths are resolved against the directory of the project file
  Query: /SmokeTests
- Provider: Yaml@1
  Name: Integrity checks
  Connection string: ./IntegrityChecks.yaml
  Query: /IntegrationChecks
# - ...  abbreviated

The same technique splits tests inside the project file: name the project file itself in Connection string and point Query at a node of your own.

Hardcoded data

Data to compare against — the expected result of a query on a relational data source, say — can be hardcoded in the project file or any other YAML file and served by Yaml@1:

Data sources:
- Name: ExpectedData
  Provider: Yaml@1
  Connection string: ./MyCatProject.cat.yaml # the project file, or any other file holding the data

Tests:
- Name:
  Description: Sample dataset contains problems for two invoices, the test should identify them
  First Data Source: Accounting
  First Query: SELECT InvoiceID FROM fn_GetProblematicInvoices();
  Second Data Source: ExpectedData
  Second Query: /Expected data

Expected data:
- InvoiceID: 202000483490
- InvoiceID: 202330409494

JSON inside YAML

YAML is a superset of JSON: JSON written inside a YAML file is valid YAML. JSON is the more concise way of writing hardcoded data and is easier to generate.

# an empty array:
Expected Data: []
# an array with data:
Other Data: ["Red", "Green", "Blue"]
# an object in JSON syntax:
Expected Employee: { "First name": "Tereza", "Last name": "Černá", "Department": "Testing" }

Connection string

The path to the YAML file. A relative path is resolved against the directory of the project file. The key is also accepted as File path; when neither is present the provider falls back to Data.yaml — see Connection string on the data source properties page.

Settings

None beyond the file path.

Query

A node path: the keys leading from the root of the document to the list to read, separated by slashes, starting with / for the document root — /Tests, /Data sources, /Structure/Departments. The node the path ends at must be a YAML list; every item of the list becomes one row, its keys the columns. Yaml@1 does not accept SQL.

To read the departments out of this file

Date: 2023-05-02
Company: ABC
Structure:
    Departments:
    - Name: Sales
    - Name: Marketing
    - Name: HR

the Query is /Structure/Departments: CAT walks the list and returns a result set with one column (Name) and three rows.

Prerequisites

None. Nothing to install; Windows and Linux alike.

Limitations

Yaml@1 reads one list at a time. A row is built from the keys of one item of that list, and nothing else: values from the item’s parents or from nested mappings and lists inside the item are not combined into the row. A list directly at the root of the document (a file that starts with - ) cannot be read — the list must sit under a key. The items of the list must be mappings (- Name: Sales), not bare scalars (- Sales).

Serving test and data source definitions

Yaml@1 is the provider that serves lists of definitions from the project file itself, and it serves them from any other YAML file the same way: a node path whose list items carry the keys of a test, data source or query definition. It is also the only provider whose lists can be written back to — CAT Studio saves edited definitions into a YAML-backed list, the implicit one in the project file included; lists served by any other provider are read-only to CAT.

← Teradata@1
CsvOleDB@1 →