feat: add docs about assertion trees in cli

Signed-off-by: Charles-Edouard Brétéché <charles.edouard@nirmata.com>

content/en/docs/kyverno-cli/assertion-trees.md

@@ -0,0 +1,77 @@
+---
+title: Working with Assertion Trees
+description: Advanced testing with the Kyverno CLI
+weight: 20
+---
+
+Kyverno 1.12 introduced assertion trees support in the `test` command.
+
+The purpose of assertion trees is to offer more flexibility than the traditional syntax in `results`.
+
+Assertion trees reside under the `checks` stanza as shown in the example below:
+
+```yaml
+checks:
+- match:
+    resource:
+      kind: Namespace
+      metadata:
+        name: hello-world-namespace
+    policy:
+      kind: ClusterPolicy
+      metadata:
+        name: sync-secret
+    rule:
+      name: sync-my-secret
+  assert:
+    status: pass
+  error:
+    (status != 'pass'): true
+```
+
+## Composition of a check item
+
+A check is made of the following parts:
+
+- A `match` statement to select the elements considered by a check. This match can act on the resource, the policy and/or the rule. It is not limited to matching by kind or name but can match on anything in the payload (labels, annotations, etc...).
+- An `assert` statement defining the conditions to verify on the matched elements.
+- An `error` statement (the opposite of an `assert`) defining the conditions that must NOT evaluate to `true` on the matched elements.
+
+In the example above the `check` is matching Namespace elements named `hello-world-namespace` for the cluster policy named `sync-secret` and rule named `sync-my-secret`. For those elements the status is expected to be equal to `pass` and the expression `(status != 'pass')` is NOT expected to be true.
+
+## Examples
+
+Implementation is based on [Kyverno JSON - assertion trees](https://kyverno.github.io/kyverno-json/latest/policies/policies/). Please refer to the documentation for more details on the syntax.
+
+### Select all results
+
+To select all results, all you need to do is to provide an empty match statement:
+
+```yaml
+
+- match: {} # this will match everything
+  assert:
+    # ...
+  error:
+    # ...
+```
+
+### Select based on labels
+
+To select results based on labels, specify those labels in the stanza where they apply:
+
+```yaml
+- match:
+    resource:
+      metadata:
+        labels:
+          foo: bar
+    policy:
+      metadata:
+        labels:
+          bar: baz
+  assert:
+    # ...
+  error:
+    # ...
+```

content/en/docs/kyverno-cli/usage/_index.md

@@ -1,7 +1,7 @@
 ---
 title: CLI Commands
 description: Using the Kyverno CLI
-weight: 20
+weight: 30
 ---
 
 This section covers the main Kyverno CLI commands, for other commands please refer to the [Reference documentation](../reference/_index.md)

content/en/docs/kyverno-cli/usage/test.md

@@ -54,7 +54,13 @@ results:
   cloneSourceResource: <file_name.yaml> # when testing a generate rule that uses `clone` object this field is required.
   kind: <kind>
   result: pass
-```
+checks:
+- match:
+    resource: {} # match results associated with a resource
+    policy: {} # match results associated with a policy
+    rule: {} # match results associated with a rule
+  assert: {} # assertion to validate the content of matched elements
+  error: {} # negative assertion to validate the content of matched elements
 
 The test declaration consists of the following parts:
 
@@ -64,6 +70,7 @@ The test declaration consists of the following parts:
 4. The `variables` element which defines a file in which variables and their values are stored for use in the policy test. Optional depending on policy content.
 5. The `userinfo` element which declares admission request data for subjects and roles. Optional depending on policy content.
 6. The `results` element which declares the expected results. Depending on the type of rule being tested, this section may vary.
+7. The `checks` element which declares the assertions to be evaluted against the results (see [Working with Assertion Trees](../assertion-trees.md)).
 
 If needing to pass variables, such as those from [external data sources](../../writing-policies/external-data-sources.md) like context variables built from [API calls](../../writing-policies/external-data-sources.md#variables-from-kubernetes-api-server-calls) or others, a `variables.yaml` file can be defined with the same format as accepted with the `apply` command. If a variable needs to contain an array of strings, it must be formatted as JSON encoded. Like with the `apply` command, variables that begin with `request.object` normally do not need to be specified in the variables file as these will be sourced from the resource. Policies which trigger based upon `request.operation` equaling `CREATE` do not need a variables file. The CLI will assume a value of `CREATE` if no variable for `request.operation` is defined.