Unit Testing

🚧
Use caution when unit testing transforms that mutate production resources!

Transforms can be tested with the Substation CLI tool. Unit testing requires this configuration schema:

{
  tests: [
    {
      name: 'my-passing-test',
      // Generates the test message '{"a": true}' which
      // is run through the configured transforms and
      // then checked against the condition.
      transforms: [
        sub.tf.test.message({ value: {a: true} }),
      ],
      // Checks if key 'x' == 'true'.
      condition: sub.cnd.str.eq({ object: {source_key: 'x'}, value: 'true' }),
    },
    {
      name: 'my-failing-test',
      transforms: [
        sub.tf.test.message({ value: {a: true} }),
      ],
      // Checks if key 'y' == 'true'.
      condition: sub.cnd.str.eq({ object: {source_key: 'y'}, value: 'true' }),
    },
  ],
  // Copies the value of key 'a' to key 'x'.
  transforms: [
    sub.tf.obj.cp({ object: { source_key: 'a', target_key: 'x' } }),
  ],
}

Each test must contain:

Name: Uniquely identifies the test.
Transforms: The messages that will be unit tested.
Condition: Asserts if the test is a success or failure.

Tests are always run against every transform in the config. It's recommended to test configs as individual units (of one or more transforms) spread across multiple files that are imported into a larger config, like this:

local foo = import 'foo.libsonnet';

{
  transforms:
    foo.transforms
    // These are not tested.
    + [
      sub.tf.send.stdout(),
    ],
}

{
  tests: [
    {
      name: 'my-passing-test',
      transforms: [
        sub.tf.test.message({ value: {a: true} }),
      ],
      condition: sub.cnd.str.eq({ object: {source_key: 'x'}, value: 'true' }),
    },
  ],
  // These are tested.
  transforms: [
    sub.tf.obj.cp({ object: { source_key: 'a', target_key: 'x' } }),
  ],
}

It is important to note that some tests only work when run from the local directory. This is due to reliance on files in that directory, and will otherwise return a config error:

// This JSON file must be local to the Substation app. Absolute paths are
// recommended. Files accessible over HTTPS and hosted in AWS S3 also work.
local kv = sub.kv_store.json_file({ file: 'kv.json' });

{
  transforms: [
    ...
  ],
}

WARNING: Use caution when testing transforms that mutate production resources, such as enrichment and send transforms. Testing these transforms may have unintended side effects, such as accidentally sending test data to production systems.

🚧Use caution when unit testing transforms that mutate production resources!

🚧
Use caution when unit testing transforms that mutate production resources!