docs(examples): Add Unit Tests (#245)

examples/condition/meta/config.jsonnet

@@ -4,9 +4,18 @@
 local sub = import '../../../substation.libsonnet';
 
 {
-  concurrency: 1,
+  tests: [
+    {
+      name: 'meta',
+      transforms: [
+        sub.tf.test.message({ value: ["[email protected]","[email protected]"] }),
+        sub.tf.send.stdout(),
+      ],
+      // Asserts that the message is equal to 'true'.
+      condition: sub.cnd.str.eq({ value: 'true' }),
+    }
+  ],
   transforms: [
-    sub.tf.send.stdout(),
     // In real-world deployments, the match decision is typically used
     // to summarize an array of values. For this example, the decision
     // is represented as a boolean value and printed to stdout.
@@ -15,7 +24,9 @@ local sub = import '../../../substation.libsonnet';
         {
           condition: sub.cnd.meta.any({
             object: { source_key: '@this' },  // Required to interpret the input as a JSON array.
-            inspectors: [sub.cnd.str.ends_with(settings={ value: '@brex.com' })],
+            conditions: [
+              sub.cnd.str.ends_with({ value: 'brex.com' }),
+            ],
           }),
           transforms: [
             sub.tf.obj.insert({ object: { target_key: 'meta result' }, value: true }),

examples/condition/number/config.jsonnet

@@ -2,7 +2,20 @@
 local sub = import '../../../substation.libsonnet';
 
 {
-  concurrency: 1,
+  tests: [
+    {
+      name: 'number',
+      transforms: [
+        sub.tf.test.message({ value: {"sourcePort":22,"bytes":20000} }),
+        sub.tf.send.stdout(),
+      ],
+      // Asserts that the conditional transforms were applied.
+      condition: sub.cnd.all([
+        sub.cnd.str.eq({ obj: {src: 'service'}, value: 'SSH' }),
+        sub.cnd.str.eq({ obj: {src: 'severity'}, value: 'high' }),
+      ])
+    }
+  ],
   transforms: [
     sub.tf.meta.switch({ cases: [
       {

examples/condition/string/config.jsonnet

@@ -2,14 +2,27 @@
 local sub = import '../../../substation.libsonnet';
 
 {
-  concurrency: 1,
+  tests: [
+    {
+      name: 'string',
+      transforms: [
+        sub.tf.test.message({ value: {"action":"ACCEPT","vpcId":"vpc-2b3c4d5e"} }),
+        sub.tf.send.stdout(),
+      ],
+      // Asserts that the conditional transforms were applied.
+      condition: sub.cnd.all([
+        sub.cnd.str.eq({ obj: {src: 'outcome'}, value: 'Allow' }),
+        sub.cnd.str.eq({ obj: {src: 'priority'}, value: 'high' }),
+      ])
+    }
+  ],
   transforms: [
     sub.tf.meta.switch({ cases: [
       {
         condition: sub.cnd.str.eq({ obj: { src: 'action' }, value: 'ACCEPT' }),
         transforms: [
           // This overwrites the value of the 'action' key.
-          sub.tf.obj.insert({ obj: { trg: 'action' }, value: 'Allow' }),
+          sub.tf.obj.insert({ obj: { trg: 'outcome' }, value: 'Allow' }),
         ],
       },
     ] }),

examples/transform/aggregate/sample/config.jsonnet

@@ -4,17 +4,40 @@
 local sub = import '../../../../substation.libsonnet';
 
 {
-  concurrency: 1,
+  tests: [
+    {
+      name: 'sample',
+      transforms: [
+        sub.tf.test.message({ value: {"a":"b"}}),
+        sub.tf.test.message({ value: {"c":"d"}}),
+        sub.tf.test.message({ value: {"e":"f"}}),
+        sub.tf.test.message({ value: {"g":"h"}}),
+        sub.tf.test.message({ value: {"i":"j"}}),
+        sub.tf.test.message({ value: {"k":"l"}}),
+        sub.tf.test.message({ value: {"m":"n"}}),
+        sub.tf.test.message({ value: {"o":"p"}}),
+        sub.tf.test.message({ value: {"q":"r"}}),
+        sub.tf.test.message({ value: {"s":"t"}}),
+        sub.tf.test.message({ value: {"u":"v"}}),
+        sub.tf.test.message({ value: {"w":"x"}}),
+        sub.tf.test.message({ value: {"y":"z"}}),
+        sub.tf.test.message({ value: " "}),
+        sub.tf.send.stdout(),
+      ],
+      // Asserts that the message is '{"c":"d"}'.
+      condition: sub.cnd.num.len.greater_than({ value: 0 }),
+    }
+  ],
   transforms: [
     // Events are aggregated into an array. This example has a sample
-    // rate of up to 1/10. By default, the sample rate will be lower if
-    // fewer than 10 events are processed by Substation.
-    sub.tf.aggregate.to.array({ object: { target_key: 'meta sample' }, batch: { count: 10 } }),
+    // rate of up to 1/5. By default, the sample rate will be lower if
+    // fewer than 5 events are processed by Substation.
+    sub.tf.aggregate.to.array({ object: { target_key: 'meta sample' }, batch: { count: 5 } }),
     // A strict sample rate can be enforced by dropping any events that
-    // contain the `sample` key, but do not have a length of 10.
+    // contain the `sample` key, but do not have a length of 5.
     sub.tf.meta.switch(settings={ cases: [
       {
-        condition: sub.cnd.num.len.eq({ object: { source_key: 'meta sample' }, value: 10 }),
+        condition: sub.cnd.num.len.eq({ object: { source_key: 'meta sample' }, value: 5 }),
         transforms: [
           sub.tf.object.copy({ object: { source_key: 'meta sample.0' } }),
         ],

examples/transform/aggregate/summarize/config.jsonnet

@@ -4,6 +4,38 @@
 local sub = import '../../../../substation.libsonnet';
 
 {
+  tests: [
+    {
+      name: 'summarize',
+      transforms: [
+        sub.tf.test.message({ value: {"client":"10.1.1.2","server":"8.8.8.8","bytes":11,"timestamp":1674429049} }),
+        sub.tf.test.message({ value: {"client":"10.1.1.3","server":"8.8.4.4","bytes":20,"timestamp":1674429050} }),
+        sub.tf.test.message({ value: {"client":"10.1.1.2","server":"8.8.4.4","bytes":15,"timestamp":1674429051} }),
+        sub.tf.test.message({ value: {"client":"10.1.1.3","server":"8.8.8.8","bytes":8,"timestamp":1674429052} }),
+        sub.tf.test.message({ value: {"client":"10.1.1.2","server":"8.8.8.8","bytes":25,"timestamp":1674429053} }),
+        sub.tf.test.message({ value: {"client":"10.1.1.4","server":"1.2.3.4","bytes":2400,"timestamp":1674429054} }),
+        sub.tf.test.message({ value: {"client":"10.1.1.2","server":"8.8.4.4","bytes":23,"timestamp":1674429055} }),
+        sub.tf.test.message({ value: {"client":"10.1.1.3","server":"8.8.8.8","bytes":12,"timestamp":1674429056} }),
+        sub.tf.test.message({ value: {"client":"10.1.1.2","server":"8.8.4.4","bytes":18,"timestamp":1674429057} }),
+        sub.tf.test.message({ value: {"client":"10.1.1.3","server":"8.8.8.8","bytes":6,"timestamp":1674429058} }),
+        sub.tf.test.message({ value: {"client":"10.1.1.2","server":"8.8.4.4","bytes":23,"timestamp":1674429059} }),
+        sub.tf.test.message({ value: {"client":"10.1.1.3","server":"8.8.8.8","bytes":12,"timestamp":1674429060} }),
+        sub.tf.test.message({ value: {"client":"10.1.1.2","server":"8.8.4.4","bytes":18,"timestamp":1674429061} }),
+        sub.tf.test.message({ value: {"client":"10.1.1.3","server":"8.8.8.8","bytes":6,"timestamp":1674429062} }),
+        sub.tf.test.message({ value: {"client":"10.1.1.2","server":"8.8.8.8","bytes":11,"timestamp":1674429063} }),
+        sub.tf.test.message({ value: {"client":"10.1.1.3","server":"8.8.4.4","bytes":20,"timestamp":1674429064} }),
+        sub.tf.test.message({ value: {"client":"10.1.1.2","server":"8.8.4.4","bytes":15,"timestamp":1674429065} }),
+        sub.tf.test.message({ value: {"client":"10.1.1.3","server":"8.8.8.8","bytes":8,"timestamp":1674429066} }),
+        sub.tf.test.message({ value: {"client":"10.1.1.2","server":"8.8.8.8","bytes":25,"timestamp":1674429067} }),
+        sub.tf.send.stdout(),
+      ],
+      // Asserts that each message has the 'count' and 'bytes_total' fields.
+      condition: sub.cnd.all([
+        sub.cnd.num.len.greater_than({ obj: {src: 'count'}, value: 0 }),
+        sub.cnd.num.len.greater_than({ obj: {src: 'bytes_total'}, value: 0 }),
+      ])
+    }
+  ],
   transforms: [
     // Events are aggregated into arrays based on their client and server fields.
     // The resulting array is put into a new field named "reduce".

examples/transform/array/extend/config.jsonnet

@@ -2,7 +2,17 @@
 local sub = import '../../../../substation.libsonnet';
 
 {
-  concurrency: 1,
+  tests: [
+    {
+      name: 'extend',
+      transforms: [
+        sub.tf.test.message({ value: {"a":[1,2],"z":[3,4]} }),
+        sub.tf.send.stdout(),
+      ],
+      // Asserts that 'a' contains 4 elements.
+      condition: sub.cnd.num.len.eq({ obj: {src: 'a'}, value: 4 }),
+    }
+  ],
   transforms: [
     // Append the value of `z` to `a` (using the `-1` array index).
     sub.tf.object.copy({ object: { source_key: 'z', target_key: 'a.-1' } }),

examples/transform/array/flatten/config.jsonnet

@@ -2,7 +2,17 @@
 local sub = import '../../../../substation.libsonnet';
 
 {
-  concurrency: 1,
+  tests: [
+    {
+      name: 'extend',
+      transforms: [
+        sub.tf.test.message({ value: {"a":[1,2,[3,4]]} }),
+        sub.tf.send.stdout(),
+      ],
+      // Asserts that 'a' contains 4 elements.
+      condition: sub.cnd.num.len.eq({ obj: {src: 'a'}, value: 4 }),
+    }
+  ],
   transforms: [
     // Flatten by copying the value and chaining GJSON's `@flatten` operator.
     sub.tf.obj.cp({ object: { source_key: 'a|@flatten', target_key: 'a' } }),

examples/transform/array/flatten_deep/config.jsonnet

@@ -2,7 +2,17 @@
 local sub = import '../../../../substation.libsonnet';
 
 {
-  concurrency: 1,
+  tests: [
+    {
+      name: 'extend',
+      transforms: [
+        sub.tf.test.message({ value: {"a":[1,2,[3,4,[5,6]]]} }),
+        sub.tf.send.stdout(),
+      ],
+      // Asserts that 'a' contains 6 elements.
+      condition: sub.cnd.num.len.eq({ obj: {src: 'a'}, value: 6 }),
+    }
+  ],
   transforms: [
     // Flatten by copying the value and chaining GJSON's `@flatten` operator
     // with the `deep` option.

examples/transform/array/group/config.jsonnet

@@ -5,11 +5,30 @@ local sub = import '../../../../substation.libsonnet';
 local files_key = 'meta files';
 
 {
-  concurrency: 1,
+  tests: [
+    {
+      name: 'group',
+      transforms: [
+        sub.tf.test.message({ value: {"file_name":["foo.txt","bar.html"],"file_type":["text/plain","text/html"],"file_size":[100,500]} }),
+        sub.tf.send.stdout(),
+      ],
+      // Asserts that each element in the array contains these keys:
+      //  - file_name
+      //  - file_type
+      //  - file_size
+      //  - file_extension
+      condition: sub.cnd.meta.all({
+        object: { source_key: '@this' },
+        conditions: [
+          sub.cnd.num.len.greater_than({ obj: { src: 'file_type' }, value: 0 }),
+          sub.cnd.num.len.greater_than({ obj: { src: 'file_size' }, value: 0 }),
+          sub.cnd.num.len.greater_than({ obj: { src: 'file_name' }, value: 0 }),
+          sub.cnd.num.len.greater_than({ obj: { src: 'file_extension' }, value: 0 }),
+        ],
+      })
+    }
+  ],
   transforms: [
-    // This example sends data to stdout at each step to iteratively show
-    // how the data is transformed.
-    sub.tf.send.stdout(),
     // Copy the object to metadata, where it is grouped.
     sub.tf.obj.cp({ object: { target_key: files_key } }),
     // Elements from the file_name array are transformed and derived file extensions