### Install Chainsaw via Go Install

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/cicd/gh-action.md

Example of installing Chainsaw from its main branch using `go install`. This requires Go to be installed in the workflow environment.

```yaml
jobs:
  example:
    runs-on: ubuntu-latest

    permissions: {}

    name: Install Chainsaw via go install
    steps:
      - name: Install go
        uses: actions/setup-go@v4
        with:
          go-version: '1.21'
      - name: Install Chainsaw
        uses: kyverno/action-install-chainsaw@v0.1.0
        with:
          release: main
      - name: Check install
        run: chainsaw version
```

--------------------------------

### Install Chainsaw with Default Version

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/cicd/gh-action.md

Example of installing Chainsaw using the default version provided by the action. This is useful when the latest stable version is desired.

```yaml
jobs:
  example:
    runs-on: ubuntu-latest

    permissions: {}

    name: Install Chainsaw
    steps:
      - name: Install Chainsaw
        uses: kyverno/action-install-chainsaw@v0.1.0
      - name: Check install
        run: chainsaw version
```

--------------------------------

### Install Chainsaw with Cosign Verification

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/cicd/gh-action.md

Example demonstrating how to install Chainsaw with signature verification enabled using Cosign. This enhances security by ensuring the downloaded binary is authentic.

```yaml
jobs:
  example:
    runs-on: ubuntu-latest

    permissions: {}

    name: Install Chainsaw
    steps:
      - name: Install Cosign
        uses: sigstore/cosign-installer@v3.1.1
      - name: Install Chainsaw
        uses: kyverno/action-install-chainsaw@v0.1.0
        with:
          verify: true
      - name: Check install
        run: chainsaw version
```

--------------------------------

### Describe Pods by Name Prefix

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/operations/helpers/describe.md

This example demonstrates how to describe pods whose names start with a specific prefix. The `name` field accepts a string to match against pod names.

```yaml
apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: example
spec:
  steps:
  - try: ...
    catch:
    - describe:
        apiVersion: v1
        kind: Pod
        # describe pods that have a name starting with the provided `my-pod`
        name: my-pod
```

--------------------------------

### Install Chainsaw using Homebrew

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/quick-start/install.md

Installs the Chainsaw binary using Homebrew after adding the tap. Always specify the tap name to ensure the correct tool is installed.

```bash
brew install kyverno/chainsaw/chainsaw
```

--------------------------------

### Print Pod Logs by Name Prefix

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/operations/helpers/logs.md

This example demonstrates fetching logs from pods whose names start with a specific prefix. This is helpful when you have multiple pods with a common naming convention and want to inspect a particular set.

```yaml
apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: example
spec:
  steps:
  - try: ...
    catch:
    - podLogs:
        # pods that have a name starting with the provided `my-pod`
        name: my-pod
```

--------------------------------

### Install Chainsaw with Pinned Version

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/cicd/gh-action.md

Example of pinning a specific version of Chainsaw for installation in a GitHub workflow. This ensures consistent behavior across runs.

```yaml
jobs:
  example:
    runs-on: ubuntu-latest

    permissions: {}

    name: Install Chainsaw
    steps:
      - name: Install Chainsaw
        uses: kyverno/action-install-chainsaw@v0.1.0
        with:
          release: v0.0.9
      - name: Check install
        run: chainsaw version
```

--------------------------------

### Install Chainsaw using go install

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/quick-start/install.md

Installs the latest version of Chainsaw directly using the Go toolchain.

```bash
go install github.com/kyverno/chainsaw@latest
```

--------------------------------

### StepTemplate Example with Bindings

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/step-template/index.md

An example StepTemplate that applies and asserts a file, where the filename is determined by a binding.

```yaml
apiVersion: chainsaw.kyverno.io/v1alpha1
kind: StepTemplate
metadata:
  name: quick-start
spec:
  try:
  - apply:
      file: ($file)
  - assert:
      file: ($file)
```

--------------------------------

### Install Chainsaw on NixOS

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/quick-start/install.md

Installs the 'kyverno-chainsaw' package on NixOS using the 'nix-env' command.

```bash
nix-env -iA nixos.kyverno-chainsaw
```

--------------------------------

### Trim Prefix Example 2

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/jp/examples/trim_prefix.md

Shows that the original string is returned if the prefix does not match.

```Go
trim_prefix('foobar', 'baz') == 'foobar'
```

--------------------------------

### Proxy Operation Example

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/operations/helpers/proxy.md

This example demonstrates how to configure a proxy request to a Kubernetes Service. It targets the `kyverno-svc-metrics` service in the `kyverno` namespace, proxies requests to the `metrics-port`, and sends them to the `/metrics` path. The output is decoded using `x_metrics_decode`.

```yaml
apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: example
spec:
  skip: true
  steps:
  - try:
    - proxy:
        # proxy request to the `kyverno-svc-metrics` service in the `kyverno` namespace
        apiVersion: v1
        kind: Service
        namespace: kyverno
        name: kyverno-svc-metrics
        # proxy request to the `metrics-port` port of the service
        port: metrics-port
        # send request to the `/metrics` path
        path: /metrics
        outputs:
          # decode received metrics and create an output with the results
        - name: metrics
          value: (x_metrics_decode($stdout))
```

--------------------------------

### Modulo Operation Example

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/jp/examples/modulo.md

Demonstrates the modulo operation. The divisor must be non-zero, and arguments must be integers.

```Go
modulo(`10`, `3`) == `1`
```

--------------------------------

### Basic Command Execution

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/operations/command.md

A simple example of executing a command with arguments within a test step.

```yaml
apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: example
spec:
  steps:
  - try:
    - command:
        entrypoint: echo
        args:
        - hello chainsaw
```

--------------------------------

### Trim Prefix Example 1

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/jp/examples/trim_prefix.md

Demonstrates trimming a prefix that exists at the beginning of the string.

```Go
trim_prefix('foobar', 'foo') == 'bar'
```

--------------------------------

### Get Pods by Name Prefix

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/operations/helpers/get.md

Fetches Pods whose names start with a specific prefix. This is useful for targeting resources created with a predictable naming convention.

```yaml
apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: example
spec:
  steps:
  - try: ...
    catch:
    - get:
        apiVersion: v1
        kind: Pod
        # get pods that have a name starting with the provided `my-pod`
        name: my-pod
```

--------------------------------

### Label Match: Exact Match True

Source: https://github.com/kyverno/chainsaw/blob/main/website/jp/examples/label_match.md

Shows an example where both sets of labels are identical, resulting in true.

```go
label_match(`{"app":"foo","env":"prod"}`, `{"app":"foo","env":"prod"}`) == `true`
```

--------------------------------

### Trim Prefix Example 3

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/jp/examples/trim_prefix.md

Illustrates that an empty prefix results in the original string being returned.

```Go
trim_prefix('foobar', '') == 'foobar'
```

--------------------------------

### Floor Function Example

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/jp/examples/floor.md

Demonstrates the basic usage of the floor function. Ensure the input is a valid number.

```plaintext
floor(`1.9`) == `1`
```

--------------------------------

### label_match Examples

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/jp/examples/label_match.md

Demonstrates various scenarios of the label_match function, including subset, exact match, and empty object comparisons. Object arguments must be enclosed in backticks.

```go
label_match(`{"app":"foo","env":"prod"}`, `{"app":"foo"}`) == `true`
```

```go
label_match(`{"app":"foo","env":"prod"}`, `{"app":"foo","env":"prod"}`) == `true`
```

```go
label_match(`{"app":"foo"}`, `{"app":"foo","env":"prod"}`) == `false`
```

```go
label_match(`{"app":"foo"}`, `{}`) == `true`
```

--------------------------------

### Basic Script Execution

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/operations/script.md

A simple example of running a script that echoes a string. The default shell is `sh`.

```yaml
apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: example
spec:
  steps:
  - try:
    - script:
        content: |
          echo "hello chainsaw"
```

--------------------------------

### Apply Resources using Glob Pattern

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/operations/apply.md

This example demonstrates applying multiple Kubernetes resources by specifying a glob pattern for file names.

```yaml
apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: example
spec:
  steps:
  - try:
    - apply:
        # use glob pattern
        file: "configs/*.yaml"
```

--------------------------------

### Verify Chainsaw Installation

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/quick-start/install.md

Checks the installed Chainsaw version after compiling from source.

```bash
./chainsaw version
```

--------------------------------

### Install Chainsaw on Non-NixOS

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/quick-start/install.md

Installs the 'kyverno-chainsaw' package on systems not running NixOS using 'nix-env'. Note that this method permanently modifies a local profile.

```bash
nix-env -iA nixpkgs.kyverno-chainsaw
```

--------------------------------

### Create a Local Kubernetes Cluster with Kind

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/quick-start/run-tests.md

Use this command to create a local Kubernetes cluster with kind. Ensure you have kind installed and configured.

```bash
# create cluster
kind create cluster --image "kindest/node:v1.29.4"
```

--------------------------------

### Find First Occurrence (Default Start)

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/jp/examples/find_first.md

Finds the first occurrence of 'string' starting from index 0. Returns the index of the match.

```go
find_first('subject string', 'string', `0`) == `8`
```

--------------------------------

### StepTemplate Invocation Example

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/step-template/index.md

Demonstrates how a test step can use a StepTemplate, specifying the template file and providing bindings to override defaults.

```yaml
apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: example
spec:
  steps:
  - use:
      # path to the file containing the step template, relative to this test file
      template: step-template.yaml
      with:
        # bindings passed to the template; override any same-named template defaults
        bindings:
        - name: file
          value: configmap.yaml
```

--------------------------------

### Find First Occurrence (Start at Match)

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/jp/examples/find_first.md

Finds the first occurrence of 'string' starting from index 8. Returns the index of the match.

```go
find_first('subject string', 'string', `8`) == `8`
```

--------------------------------

### Example Chainsaw Configuration

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/configuration/file.md

This YAML defines a sample Chainsaw configuration, specifying timeouts for various operations, cleanup behavior, and execution settings like failFast and parallel execution.

```yaml
apiVersion: chainsaw.kyverno.io/v1alpha2
kind: Configuration
metadata:
  name: example
spec:
  timeouts:
    apply: 45s
    assert: 20s
    cleanup: 45s
    delete: 25s
    error: 10s
    exec: 45s
  cleanup:
    skipDelete: false
  execution:
    failFast: true
    parallel: 4
  # ...

```

--------------------------------

### Describe Pods Using Label Selector

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/operations/helpers/describe.md

This example illustrates how to describe pods that match a given label selector. The `selector` field accepts a query string for filtering.

```yaml
apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: example
spec:
  steps:
  - try: ...
    catch:
    - describe:
        apiVersion: v1
        kind: Pod
        # describe pods using a label selector query
        selector: app=my-app
```

--------------------------------

### Find First Occurrence (Basic)

Source: https://github.com/kyverno/chainsaw/blob/main/website/jp/examples/find_first.md

Demonstrates finding the first occurrence of a substring within a string. Returns the starting index.

```go
find_first('subject string', 'string', `0`) == `8`
```

```go
find_first('subject string', 'string', `8`) == `8`
```

```go
find_first('subject string', 'string', `9`) == null
```

--------------------------------

### Semver Compare: Less Than (False Case)

Source: https://github.com/kyverno/chainsaw/blob/main/website/jp/examples/semver_compare.md

Compares two semantic version strings. This example shows a case where the version is not less than the specified version.

```go
semver_compare('2.0.0', '<1.5.0') == `false`
```

--------------------------------

### Basic GitHub Action Usage

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/cicd/gh-action.md

Add this entry to your GitHub workflow YAML file to install Chainsaw. The `release` input is optional and defaults to the latest version.

```yaml
uses: kyverno/action-install-chainsaw@v0.1.0
with:
  release: v0.1.0 # optional
```

--------------------------------

### Operation Description Example

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/operations/index.md

The `description` field can be used to document the purpose of an operation within a test step.

```yaml
apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: example
spec:
  steps:
  - try:
    - description: Waits a couple of seconds
      sleep:
        duration: 3s
```

--------------------------------

### Describe Pods in a Specific Namespace

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/operations/helpers/describe.md

This example shows how to describe pods located in a specific namespace. Set the `namespace` field to the desired namespace name.

```yaml
apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: example
spec:
  steps:
  - try: ...
    catch:
    - describe:
        apiVersion: v1
        kind: Pod
        # describe pods in the namespace `foo`
        namespace: foo
```

--------------------------------

### Dynamic Cluster Creation, Registration, and Cleanup

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/examples/multi-cluster.md

This example demonstrates creating a local kind cluster, registering it dynamically for use in subsequent steps, and configuring cleanup scripts to delete the cluster and its associated files upon test termination. It highlights the lifecycle management of dynamically provisioned clusters.

```yaml
apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: example
spec:
  steps:
  - try:
    # create a local cluster
    - script:
        timeout: 1m
        content: |
          kind create cluster --name dynamic --kubeconfig ./dynamic
    # register `cleanup` operations to delete the cluster
    # at the end of the test
    cleanup:
    - script:
        content: |
          kind delete cluster --name dynamic
    - script:
        content: |
          rm -f ./dynamic
    # register the `dynamic` cluster in this step
  - clusters:
      dynamic:
        kubeconfig: ./dynamic
    # and use the `dynamic` cluster for all operations in the step
    cluster: dynamic
    try:
    - apply:
        resource:
          apiVersion: v1
          kind: ConfigMap
          metadata:
            name: quick-start
            namespace: default
          data:
            foo: bar
    - assert:
        resource:
          apiVersion: v1
          kind: ConfigMap
          metadata:
            name: quick-start
            namespace: default
          data:
            foo: bar

```

--------------------------------

### Configure Cleanup Options in Configuration File

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/configuration/options/cleanup.md

Use this YAML configuration to set cleanup options like skipping deletion and defining a delay before cleanup starts.

```yaml
apiVersion: chainsaw.kyverno.io/v1alpha2
kind: Configuration
metadata:
  name: example
spec:
  cleanup:
    skipDelete: true
    delayBeforeCleanup: 5s
```

--------------------------------

### Set Up Zsh Completion

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/quick-start/completion.md

Enable Zsh completion for your current session by sourcing the script, or configure it for all sessions by adding the source command to `~/.zshrc`. For persistent setup, save the script to a directory in your `$fpath` and update `~/.zshrc`.

```bash
source <(chainsaw completion zsh)
```

```bash
echo 'source <(chainsaw completion zsh)' >> ~/.zshrc
```

```bash
# Create a directory for completions if it doesn't exist
mkdir -p ~/.zsh/completion
# Generate and save the completion script
chainsaw completion zsh > ~/.zsh/completion/_chainsaw

# Make sure the directory is in your fpath by adding to ~/.zshrc:
echo 'fpath=(~/.zsh/completion $fpath)' >> ~/.zshrc
echo 'autoload -U compinit; compinit' >> ~/.zshrc
```

--------------------------------

### Check if Time is Within Range (True)

Source: https://github.com/kyverno/chainsaw/blob/main/website/jp/examples/time_between.md

Use time_between to verify if a date falls within a start and end date. This example returns true.

```go
time_between('2024-06-15T00:00:00Z', '2024-01-01T00:00:00Z', '2024-12-31T00:00:00Z') == `true`
```

--------------------------------

### Chainsaw Export Schemas Command Usage

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/commands/chainsaw_export_schemas.md

This shows the basic usage of the `chainsaw export schemas` command. No specific flags are used in this example.

```bash
chainsaw export schemas [flags]
```

--------------------------------

### Split String by Delimiter

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/jp/examples/split.md

Splits the input string by the specified delimiter. The third argument is ignored in this example, demonstrating the basic split functionality.

```go
split('average|-|min|-|max|-|mean|-|median', '|-|', `3`) == ['average', 'min', 'max', 'mean|-|median']
```

--------------------------------

### Set Up Fish Completion

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/quick-start/completion.md

To enable completion in Fish, redirect the output of `chainsaw completion fish` to the `chainsaw.fish` file in the Fish completions directory.

```bash
chainsaw completion fish > ~/.config/fish/completions/chainsaw.fish
```

--------------------------------

### Check if Time is Within Range (False - After)

Source: https://github.com/kyverno/chainsaw/blob/main/website/jp/examples/time_between.md

Use time_between to verify if a date falls within a start and end date. This example returns false because the date is after the range.

```go
time_between('2025-01-01T00:00:00Z', '2024-01-01T00:00:00Z', '2024-12-31T00:00:00Z') == `false`
```

--------------------------------

### Describe All Pods in Test Namespace

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/operations/helpers/describe.md

This example shows how to describe all pods within the default ephemeral test namespace. The `namespace` field is omitted, defaulting to the test namespace.

```yaml
apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: example
spec:
  steps:
  - try: ...
    catch:
    - describe:
        # describe all pods in the test namespace
        apiVersion: v1
        kind: Pod
```

--------------------------------

### Check if Time is Within Range (False - Before)

Source: https://github.com/kyverno/chainsaw/blob/main/website/jp/examples/time_between.md

Use time_between to verify if a date falls within a start and end date. This example returns false because the date is before the range.

```go
time_between('2023-06-15T00:00:00Z', '2024-01-01T00:00:00Z', '2024-12-31T00:00:00Z') == `false`
```

--------------------------------

### Chainsaw Version Command Usage

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/commands/chainsaw_version.md

This shows the basic usage of the chainsaw version command. Use this command to check the installed version of the chainsaw tool.

```bash
chainsaw version [flags]
```

--------------------------------

### Set Up Bash Completion

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/quick-start/completion.md

Source the completion script in your current session or add it to `~/.bashrc` for persistent completion. Alternatively, save the script to the bash-completion directory.

```bash
source <(chainsaw completion bash)
```

```bash
echo 'source <(chainsaw completion bash)' >> ~/.bashrc
```

```bash
# On Linux
chainsaw completion bash > /etc/bash_completion.d/chainsaw
```

```bash
# On macOS with Homebrew
chainsaw completion bash > $(brew --prefix)/etc/bash_completion.d/chainsaw
```

--------------------------------

### Describe Pods Without Events

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/operations/helpers/describe.md

This example shows how to describe pods while explicitly disabling the inclusion of events. By default, `showEvents` is true, so it must be set to `false` to exclude them.

```yaml
apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: example
spec:
  steps:
  - try: ...
    catch:
    - describe:
        apiVersion: v1
        kind: Pod
        showEvents: false
```

--------------------------------

### Configure cleanup timeout

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/quick-start/cleanup.md

Define a global cleanup timeout at the configuration level or override it on a per-test or per-step basis. This example shows setting timeouts at the test and step levels.

```yaml
apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: example
spec:
  timeouts:
    # cleanup timeout at the test level
    cleanup: 30s
  steps:
  - timeouts:
      # cleanup timeout at the step level
      cleanup: 2m
    try: ...

```

--------------------------------

### Create Chainsaw Test Manifest

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/quick-start/first-test.md

Defines a Chainsaw test named `quick-start`. It includes a single step with two operations: applying a ConfigMap from a file and asserting the ConfigMap's content using the same file.

```yaml
apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: quick-start
spec:
  steps:
  - try:
    # first operation: create the config map
    - apply:
        # file is relative to the test folder
        file: configmap.yaml
    # second operation: verify the config map exists and contains the expected data
    - assert:
        # file is relative to the test folder
        file: configmap.yaml
```

--------------------------------

### Get Current Time

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/jp/examples/time_now.md

Use this function to get the current time in RFC 3339 format. Note that the output will vary with each execution.

```Go
# returns the current time in RFC 3339 format, e.g. '2024-01-15T10:30:00Z'
time_now()
```

--------------------------------

### Find First Occurrence (Start After Match)

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/jp/examples/find_first.md

Attempts to find 'string' starting from index 9. Returns null as the substring is not found after this position.

```go
find_first('subject string', 'string', `9`) == null
```

--------------------------------

### Get Current UTC Time

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/jp/examples/time_now_utc.md

Call time_now_utc() to get the current UTC time in RFC 3339 format. The output will vary with each call.

```go
# returns the current UTC time in RFC 3339 format, e.g. '2024-01-15T10:30:00Z'
time_now_utc()
```

--------------------------------

### Run Chainsaw using nix-shell

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/quick-start/install.md

Temporarily installs and runs Chainsaw using 'nix-shell', which modifies the PATH environment variable for the current session. This is useful for testing software before permanent installation.

```bash
nix-shell -p kyverno-chainsaw
```

--------------------------------

### Map Object Property - Chainsaw Example

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/jp/examples/map.md

Extracts the 'name' property from each object in an array.

```chainsaw
map(&name, [{name: 'foo'}, {name: 'bar'}]) == ['foo', 'bar']
```

--------------------------------

### Build Chainsaw Binaries from Source

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/quick-start/install.md

Builds the Chainsaw binaries after cloning the repository. This includes tidying Go modules and running the build command.

```bash
cd chainsaw
go mod tidy
make build
```

--------------------------------

### Get event by name

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/operations/helpers/events.md

Filter events by their specific name using the `name` field.

```yaml
apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: example
spec:
  steps:
  - try: ...
    catch:
    # get event by name
    - events:
        name: my-event
```

--------------------------------

### Declare Bindings at Different Levels

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/general/bindings.md

This example demonstrates how bindings can be declared at the test, step, and operation levels. It also shows how to combine bindings using the `join` function to create an environment variable.

```yaml
apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: example
spec:
  # bindings can be declared at the test level
  bindings:
  - name: chainsaw
    value: chainsaw
  steps:
    # bindings can also be declared at the step level
  - bindings:
    - name: hello
      value: hello
    try:
    - script:
        # bindings can also be declared at the operation level
        bindings:
        - name: awesome
          value: awesome
        env:
          # combined bindings together using the `join` functions and
          # assign the result to the GREETINGS environment variable
        - name: GREETINGS
          value: (join(' ', [$hello, $chainsaw, 'is', $awesome]))
        content: echo $GREETINGS

```

--------------------------------

### Map to Length - Chainsaw Example

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/jp/examples/map.md

Transforms each string element in an array to its length using the `length` function.

```chainsaw
map(&length(@), ['foo', 'foobar']) == [`3`, `6`]
```

--------------------------------

### Map to Uppercase - Chainsaw Example

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/jp/examples/map.md

Transforms all string elements in an array to uppercase using the `to_upper` function.

```chainsaw
map(&to_upper(@), ['foo', 'bar']) == ['FOO', 'BAR']
```

--------------------------------

### Chainsaw Build Command Options

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/commands/chainsaw_build.md

Available options for the chainsaw build command. The help flag displays all available flags and their descriptions.

```bash
-h, --help   help for build
```

--------------------------------

### Chainsaw Export Help Options

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/commands/chainsaw_export.md

Displays help information for the `chainsaw export` command, including available flags.

```bash
  -h, --help   help for export
```

--------------------------------

### Basic Output Usage

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/general/outputs.md

Illustrates how to define an output binding named 'OUTPUT' that captures the standard output of a script. This output can then be used in subsequent operations, for example, to set an environment variable.

```yaml
apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: example
spec:
  bindings:
  - name: chainsaw
    value: chainsaw
  steps:
  - bindings:
    - name: hello
      value: hello
    try:
    - script:
        bindings:
        - name: awesome
          value: awesome
        env:
        - name: GREETINGS
          value: (join(' ', [$hello, $chainsaw, 'is', $awesome]))
        # output is used to register a new `$OUTPUT` binding
        outputs:
        - name: OUTPUT
          value: ($stdout)
        content: echo $GREETINGS
    - script:
        # output from the previous operation is used
        # to configure an evironment variable
        env:
        - name: INPUT
          value: ($OUTPUT)
        content: echo $INPUT
```

--------------------------------

### Create ConfigMap Manifest

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/quick-start/first-test.md

Defines a Kubernetes ConfigMap resource with the name `chainsaw-quick-start` and sample data. This manifest will be applied during the test.

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: chainsaw-quick-start
data:
  foo: bar
```

--------------------------------

### Get Length of Array

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/jp/examples/length.md

Returns the number of elements in an array. Use this to determine the size of array-like structures.

```plaintext
length([`10`,`15`,`20`]) == `3`
```

--------------------------------

### Print All Pod Logs in Test Namespace

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/operations/helpers/logs.md

This example shows how to print logs from all pods within the current test namespace. It's useful for debugging or verifying the state of pods created during a test.

```yaml
apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: example
spec:
  steps:
  - try: ...
    catch:
    # all pods in the test namespace
    - podLogs: {}
```

--------------------------------

### Custom Shell and Arguments for Script

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/operations/script.md

Override the default shell and its arguments. This example uses `bash` with the `-c` flag.

```yaml
apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: example
spec:
  steps:
  - try:
    - script:
        # use `bash` shell
        shell: bash
        # invoke `bash` with `-c`
        shellArgs:
        - -c
        content: |
          echo "hello chainsaw"
```

--------------------------------

### Chainsaw Export Schemas Help Option

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/commands/chainsaw_export_schemas.md

This demonstrates how to access help for the `chainsaw export schemas` command. The `-h` or `--help` flags display available options.

```bash
  -h, --help   help for schemas
```

--------------------------------

### Chainsaw Version Command Options

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/commands/chainsaw_version.md

Lists the available options for the chainsaw version command. The help flag provides further assistance.

```bash
  -h, --help   help for version
```

--------------------------------

### Get Kubernetes Deployment

Source: https://github.com/kyverno/chainsaw/blob/main/website/jp/examples/x_k8s_get.md

Use this function to retrieve a specific Kubernetes Deployment. For clustered resources, the namespace can be left empty.

```bash
# $client is a binding pointing to a Kubernetes client

x_k8s_get($client, 'apps/v1', 'Deployment', 'crossplane-system', 'crossplane')
```

--------------------------------

### Set Up PowerShell Completion

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/quick-start/completion.md

Enable PowerShell completion by piping the output of `chainsaw completion powershell` to `Invoke-Expression`. To make this persistent, append the command to your PowerShell profile.

```powershell
chainsaw completion powershell | Out-String | Invoke-Expression
```

```powershell
# Find the profile path
# echo $PROFILE

# Add the completion command to your profile
chainsaw completion powershell | Out-String | Out-File -Append $PROFILE
```

--------------------------------

### Get Length of Empty Array

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/jp/examples/length.md

Returns 0 for an empty array. This confirms the function correctly handles zero-element collections.

```plaintext
length([]) == `0`
```

--------------------------------

### starts_with Function

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/jp/examples/starts_with.md

The `starts_with` function reports whether the input string begins with the provided string prefix argument.

```APIDOC
## starts_with(string, string)

### Description
Reports whether the input string begins with the provided string prefix argument.

### Parameters
#### Path Parameters
- **string** (string) - Required - The input string to check.
- **string** (string) - Required - The prefix string to compare against.

### Examples
```
starts_with('foobar', 'foo') == `true`
```

```
starts_with('foobar', 'bar') == `false`
```
```

--------------------------------

### Build Test Documentation

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/guides/test-docs.md

Use this command to automatically discover tests and document their steps and operations within `try`, `catch`, and `finally` blocks. Specify the directory containing your Chainsaw tests using the `--test-dir` flag.

```bash
chainsaw build docs --test-dir path/to/chainsaw/tests
```

--------------------------------

### Get Element at Index with at()

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/jp/examples/at.md

Use the `at` function to retrieve an element from an array at a specified index. Ensure the index is a valid number.

```yaml
at([`10`,`15`,`20`], `1`) == `15`
```

--------------------------------

### Get Pods in Specific Namespace

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/operations/helpers/get.md

Retrieves Pods from a specified namespace. This overrides the default behavior of scoping to the test namespace.

```yaml
apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: example
spec:
  steps:
  - try: ...
    catch:
    - get:
        apiVersion: v1
        kind: Pod
        # get pods in the namespace `foo`
        namespace: foo
```

--------------------------------

### Get events in a specific namespace

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/operations/helpers/events.md

Specify a namespace using the `namespace` field to filter events from a particular Kubernetes namespace.

```yaml
apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: example
spec:
  steps:
  - try: ...
    catch:
    # get events in a specific namespace
    - events:
        namespace: foo
```

--------------------------------

### Chainsaw CLI Options

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/commands/chainsaw.md

Lists the available options for the chainsaw command. Use the help flag to display these options.

```bash
  -h, --help   help for chainsaw
```

--------------------------------

### Chainsaw Build Docs Options

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/commands/chainsaw_build_docs.md

Available options for the `chainsaw build docs` command. These flags control the output and scope of the generated documentation.

```bash
      --catalog string         Path to the built test catalog file
  -h, --help                   help for docs
      --readme-file string     Name of the built docs file (default "README.md")
      --test-dir stringArray   Directories containing test cases to run
      --test-file string       Name of the test file (default "chainsaw-test")
```

--------------------------------

### Basic Sleep Operation

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/operations/sleep.md

This example demonstrates how to use the sleep operation within a Chainsaw test to pause execution for 30 seconds.

```yaml
apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: example
spec:
  steps:
  - try:
    - sleep:
        duration: 30s
```

--------------------------------

### Set values from command line

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/examples/values.md

Configure test values directly from the command line using --set for string values or --set-string for explicitly string-typed values.

```bash
chainsaw test --set env=production --set-string version=v1.2.0
```

--------------------------------

### Check if String Starts With Prefix

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/jp/examples/starts_with.md

Use `starts_with` to determine if a string begins with a given prefix. Returns `true` if it does, `false` otherwise.

```plaintext
starts_with('foobar', 'foo') == `true`
```

```plaintext
starts_with('foobar', 'bar') == `false`
```

--------------------------------

### Get Kubernetes Server Version

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/jp/examples/x_k8s_server_version.md

This function returns the version of the connected Kubernetes cluster. It requires a client binding to interact with the cluster.

```APIDOC
## x_k8s_server_version

### Description
Returns the version of a Kubernetes cluster.

### Signature
`x_k8s_server_version(any)`

### Parameters
* **client** (any) - A binding pointing to a Kubernetes client.

### Example
```
# `$client` is a binding pointing to a Kubernetes client

x_k8s_server_version($client)
```
```

--------------------------------

### Print Pod Logs Using Label Selector

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/operations/helpers/logs.md

This example demonstrates how to filter pods based on their labels using a label selector query. This is useful for targeting pods that have specific application or component labels.

```yaml
apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: example
spec:
  steps:
  - try: ...
    catch:
    - podLogs:
        # match pods using a label selector query
        selector: app=my-app
```

--------------------------------

### Invoke Chainsaw with values from a file

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/examples/values.md

Use the --values flag followed by a file path to load test configuration from a YAML file.

```bash
chainsaw test --values ./values.yaml
```

--------------------------------

### Get JavaScript Type of String

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/jp/examples/type.md

Use the `type` function to check if a value is a string. This function returns the JavaScript type as a string.

```javascript
type('foobar') == 'string'
```

--------------------------------

### Get JavaScript Type of Null

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/jp/examples/type.md

Use the `type` function to check if a value is null. This function returns the JavaScript type as a string.

```javascript
type(null) == 'null'
```

--------------------------------

### Using JMESPath join() for Dynamic Resource Names

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/general/templating.md

Shows how to use the JMESPath `join()` function to construct dynamic resource names by concatenating strings and bindings. This example creates a unique ConfigMap name using the namespace and a literal string.

```yaml
apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: example
spec:
  steps:
  - apply:
      resource:
        apiVersion: v1
        kind: ConfigMap
        metadata:
          name: (join('-', [$namespace, 'cm']))
        data:
          foo: bar
```

--------------------------------

### Get Object Values

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/jp/examples/values.md

Use the values function to extract all values from an object into an array. This is useful for iterating over or processing object properties.

```go
values({bar:'bam',foo:'baz'}) == ['bam','baz']
```

--------------------------------

### Create Test Folder

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/quick-start/first-test.md

Creates a new directory for your test and navigates into it. This is the first step in organizing your Chainsaw tests.

```bash
# create test folder
mkdir chainsaw-quick-start

# enter test folder
cd chainsaw-quick-start
```

--------------------------------

### Get JavaScript Type of Boolean

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/jp/examples/type.md

Use the `type` function to check if a value is a boolean. This function returns the JavaScript type as a string.

```javascript
type(`false`) == 'boolean'
```

--------------------------------

### Get Pods in JSON Format

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/operations/helpers/get.md

Retrieves Pods and formats the output as JSON. This is useful for programmatic processing of the retrieved resource data.

```yaml
apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: example
spec:
  steps:
  - try: ...
    catch:
    - get:
        apiVersion: v1
        kind: Pod
        format: json
```

--------------------------------

### Configure Discovery Options with Flags

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/configuration/options/discovery.md

Apply discovery options directly via command-line flags for ad-hoc test runs. This is useful for overriding configuration file settings or for quick tests.

```bash
chainsaw test                                   \
  --test-file chainsaw-test                     \
  --full-name                                   \
  --include-test-regex 'chainsaw/.*'            \
  --exclude-test-regex 'chainsaw/exclude-.*'

```

--------------------------------

### Get all events in the test namespace

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/operations/helpers/events.md

Use an empty `events: {}` configuration to retrieve all events within the current ephemeral test namespace.

```yaml
apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: example
spec:
  steps:
  - try: ...
    catch:
    # get all events in the test namespace
    - events: {}
```

--------------------------------

### Create Resource from File

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/operations/create.md

Use this snippet to create a Kubernetes resource defined in a specific YAML file.

```yaml
apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: example
spec:
  steps:
  - try:
    - create:
        # use a specific file
        file: my-configmap.yaml
```

--------------------------------

### Ceil Function Example

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/jp/examples/ceil.md

Demonstrates rounding up a number to the next highest integer using the ceil function. Ensure the input is a valid number.

```yaml
ceil(`1.9`) == `2`
```

--------------------------------

### Convert String to String

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/jp/examples/to_string.md

Demonstrates converting a string literal to its string representation.

```go
to_string('foobar') == 'foobar'
```

--------------------------------

### semver_compare: Basic Comparisons

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/jp/examples/semver_compare.md

Demonstrates various comparison operators with semver_compare. Use this function to check version relationships.

```bash
semver_compare('1.0.0', '>1.0.0') == `false`
```

```bash
semver_compare('1.2.0', '>1.0.0') == `true`
```

```bash
semver_compare('1.0.0', '>=1.0.0') == `true`
```

```bash
semver_compare('2.0.0', '<1.5.0') == `false`
```

```bash
semver_compare('1.0.0', '=1.0.0') == `true`
```

--------------------------------

### Migrate KUTTL Configuration to Chainsaw

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/guides/kuttl-migration.md

This command migrates a KUTTL `TestSuite` file to its corresponding Chainsaw `Configuration` format. It generates a `.chainsaw.yaml` file for the converted configuration. The `--save` and `--cleanup` flags are used to manage the output and temporary files.

```bash
chainsaw migrate kuttl config path/to/kuttl/testsuite --save --cleanup
```

--------------------------------

### Get a Kubernetes Deployment

Source: https://github.com/kyverno/chainsaw/blob/main/website/docs/reference/jp/examples/x_k8s_get.md

Use this snippet to retrieve a specific Deployment resource from the Kubernetes cluster. For clustered resources, the namespace can be left empty.

```bash
# \$client is a binding pointing to a Kubernetes client

x_k8s_get($client, 'apps/v1', 'Deployment', 'crossplane-system', 'crossplane')
```

--------------------------------

### Execute Command in Chainsaw Test

Source: https://github.com/kyverno/chainsaw/blob/main/testdata/commands/migrate/kuttl/tests/out.txt

Use the `command` operation to execute a specified entrypoint with arguments. Set `skipLogOutput` to true to prevent the command's output from being logged.

```yaml
command:
        args:
        - hello world
        entrypoint: echo
        skipLogOutput: true
```