This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Documentation

1: Getting Started

1.1: Install
1.2: CLI Usage

2: Reference

2.1: Step Definitions
2.2: Matchers

3: Examples

4: Plugins

This is a placeholder page that shows you how to use this template site.

1 - Getting Started

This is a placeholder page that shows you how to use this template site.

This section is where the user documentation for your project lives - all the information your users need to understand and successfully use your project. For large documentation sets we recommend adding content under the headings in this section, though if some or all of them don’t apply to your project feel free to remove them or add your own. You can see an example of a smaller Docsy documentation site in the [Docsy User Guide](https://docsy.dev/docs/), which lives in the [Docsy theme repo](https://github.com/google/docsy/tree/master/userguide) if you'd like to copy its docs section. Other content such as marketing material, case studies, and community updates should live in the [About](/about/) and [Community](/community/) pages. Find out how to use the Docsy theme in the [Docsy User Guide](https://docsy.dev/docs/). You can learn more about how to organize your documentation (and how we organized this site) in [Organizing Your Content](https://docsy.dev/docs/best-practices/organizing-content/).

1.1 - Install

Installing BDK

Install pre-built binary

The latest releases binaries can be found in https://github.com/testernetes/bdk/releases

Container Image

Container images can be pulled from ghcr.io/testernetes/bdk:latest

Install from source

To install the latest version of BDK you must have at least Go v1.19 installed and run:

go install github.com/testernetes/bdk@latest

1.2 - CLI Usage

How to use the BDK CLI

BDK CLI Usage

Behaviour Driven Kubernetes

Usage:
  bdk [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  matchers    View matchers
  steps       View steps
  test        Run a test suite of feature files

Flags:
  -h, --help              help for bdk
  -p, --plugins strings   Additional plugin step definitions

Use "bdk [command] --help" for more information about a command.

Test

Usage:
  bdk test [-f format] features... [flags]

Flags:
  -f, --format string   the format printer (default "simple")
  -h, --help            help for test

Global Flags:
  -p, --plugins strings   Additional plugin step definitions

Where features is a set of 1 or more feature files to test.

2 - Reference

Composing features

2.1 - Step Definitions

Available step definitions for scenarios.

Composing a Scenario with Step Definitions

All steps should be prefixed with either ‘Given’, ‘When’, ‘Then’, ‘And’, ‘But’, ‘*’.

Once execution begins, for each step, Cucumber will look for a registered step definition with a matching Regexp. If it finds one, it will execute it, passing all capture group s and variables from the Regexp as arguments to the method.

The specific preposition/adverb used has no significance when Cucumber is registering or looking up step definitions.

a resource called <reference>

Assigns a reference to the resource given the in the DocString. This reference can be referred to in future steps in the same scenario. JSON and YAML formats are accepted.

Given a resource called cm:
  """
  apiVersion: v1
  kind: ConfigMap
  metadata:
    name: example
    namespace: default
  data:
    foo: bar
  """

<reference>: A short hand name for a resource.: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/ A resource can be assigned to this reference in a Context step and later referred to in an Action or Outcome step. The reference must a name that can be used as a DNS subdomain name as defined in RFC 1123. This is the same Kubernetes requirement for names, i.e. lowercase alphanumeric characters.
Additional Step Arguments: A Kubernetes manifest.: https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/ Can be yaml or json depending on the content type.

I create <reference>

Creates the referenced resource. Step will fail if the reference was not defined in a previous step.

Given a resource called cm:
  """
  apiVersion: v1
  kind: ConfigMap
  metadata:
    name: example
    namespace: default
  data:
    foo: bar
  """
And I create cm
  | field manager | example |
Then within 1s cm jsonpath '{.metadata.uid}' should not be empty

<reference>: A short hand name for a resource.: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/ A resource can be assigned to this reference in a Context step and later referred to in an Action or Outcome step. The reference must a name that can be used as a DNS subdomain name as defined in RFC 1123. This is the same Kubernetes requirement for names, i.e. lowercase alphanumeric characters.; Additional Step Arguments: (optional) A table of additional client create options.

https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/client#CreateOptions

Create Options:
| dry run       | boolean |
| field manager | string  |

I delete <reference>

Deletes the referenced resource. Step will fail if the reference was not defined in a previous step.

Given a resource called cm:
  """
  apiVersion: v1
  kind: ConfigMap
  metadata:
    name: example
    namespace: default
  data:
    foo: bar
  """
And I create cm
And I delete cm
  | grace period seconds | 30         |
  | propagation policy   | Foreground |

<reference>: A short hand name for a resource.: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/ A resource can be assigned to this reference in a Context step and later referred to in an Action or Outcome step. The reference must a name that can be used as a DNS subdomain name as defined in RFC 1123. This is the same Kubernetes requirement for names, i.e. lowercase alphanumeric characters.; Additional Step Arguments: (optional) A table of additional client delete options.

https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/client#DeleteOptions

Delete Options:
| dry run              | boolean                        |
| grace period seconds | number                         |
| propagation policy   | (Orphan|Background|Foreground) |

I evict <reference>

Evicts the referenced pod resource. Step will fail if the pod reference was not defined in a previous step.

When I evict pod
  | grace period seconds | 120 |

<reference>: A short hand name for a resource.: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/ A resource can be assigned to this reference in a Context step and later referred to in an Action or Outcome step. The reference must a name that can be used as a DNS subdomain name as defined in RFC 1123. This is the same Kubernetes requirement for names, i.e. lowercase alphanumeric characters.; Additional Step Arguments: (optional) A table of additional client delete options.

https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/client#DeleteOptions

Delete Options:
| dry run              | boolean                        |
| grace period seconds | number                         |
| propagation policy   | (Orphan|Background|Foreground) |

I exec <command> in <reference>/<container>

Executes the given command in a shell in the referenced pod and container.

When I exec "echo helloworld" in pod/app

<command>: The command to execute in the container.: https://kubernetes.io/docs/tasks/debug/debug-application/get-shell-running-container/ The command will run in a shell on the container and its outputs will be captured and can be asserted against in future steps.
<reference>: A short hand name for a resource.: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/ A resource can be assigned to this reference in a Context step and later referred to in an Action or Outcome step. The reference must a name that can be used as a DNS subdomain name as defined in RFC 1123. This is the same Kubernetes requirement for names, i.e. lowercase alphanumeric characters.
<container>: The container name.: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/ The reference must a name that can be used as a DNS subdomain name as defined in RFC 1123. This is the same Kubernetes requirement for names, i.e. lowercase alphanumeric characters.

I exec <command> in <reference>

Executes the given command in a shell in the referenced pod and default container.

When I exec "echo helloworld" in pod

<command>: The command to execute in the container.: https://kubernetes.io/docs/tasks/debug/debug-application/get-shell-running-container/ The command will run in a shell on the container and its outputs will be captured and can be asserted against in future steps.
<reference>: A short hand name for a resource.: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/ A resource can be assigned to this reference in a Context step and later referred to in an Action or Outcome step. The reference must a name that can be used as a DNS subdomain name as defined in RFC 1123. This is the same Kubernetes requirement for names, i.e. lowercase alphanumeric characters.

I patch <reference>

Patches the referenced resource. Step will fail if the reference was not defined in a previous step.

Given a resource called cm:
  """
  apiVersion: v1
  kind: ConfigMap
  metadata:
    name: example
    namespace: default
  data:
    foo: bar
  """
And I create cm
When I patch cm
  | patch | {"data":{"foo":"nobar"}} |
Then for at least 10s cm jsonpath '{.data.foo}' should equal nobar

<reference>: A short hand name for a resource.: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/ A resource can be assigned to this reference in a Context step and later referred to in an Action or Outcome step. The reference must a name that can be used as a DNS subdomain name as defined in RFC 1123. This is the same Kubernetes requirement for names, i.e. lowercase alphanumeric characters.; Additional Step Arguments: A table of additional client patch options.

https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/client#PatchOptions

Patch Options:
| patch         | string (required) |
| force         | boolean           |
| dry run       | boolean           |
| field manager | string            |

I proxy get <scheme>://<reference>:<port><path>

Create a proxy connection to the referenced pod resource and attempts a http(s) GET for the port and path. Step will fail if the reference was not defined in a previous step.

Given a resource called pod:
"""yaml
apiVersion: v1
kind: Pod
metadata:
  name: app
  namespace: default
spec:
  restartPolicy: Never
  containers:
  - command: ["busybox", "httpd", "-f", "-p", "8000"]
    image: busybox:latest
    name: server
"""
When I create pod
And within 1m pod jsonpath '{.status.phase}' should equal Running
And I proxy get http://app:8000/fake
Then pod response code should equal 404

<scheme>: The scheme of a URL.: Must be either http or https.
<reference>: A short hand name for a resource.: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/ A resource can be assigned to this reference in a Context step and later referred to in an Action or Outcome step. The reference must a name that can be used as a DNS subdomain name as defined in RFC 1123. This is the same Kubernetes requirement for names, i.e. lowercase alphanumeric characters.
<port>: Port.: The port number to request. Acceptable range is 0 - 65536.
<path>: The path of a URL.: Anything that comes after port.; Additional Step Arguments: (optional) A freeform table of additional query parameters to send with the request.



ProxyGet Options:
| string | string |

<reference> logs (should|should not) say <text>

Asserts that the referenced resource will log something within the specified duration

Given a resource called testernetes:
  """
  apiVersion: v1
  kind: Pod
  metadata:
    name: testernetes
    namespace: default
  spec:
    restartPolicy: Never
    containers:
    - command:
      - /bdk
      - --help
      image: ghcr.io/testernetes/bdk:d408c829f019f2052badcb93282ee6bd3cdaf8d0
      name: bdk
  """
When I create testernetes
Then testernetes logs should say Behaviour Driven Kubernetes

<reference>: A short hand name for a resource.: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/ A resource can be assigned to this reference in a Context step and later referred to in an Action or Outcome step. The reference must a name that can be used as a DNS subdomain name as defined in RFC 1123. This is the same Kubernetes requirement for names, i.e. lowercase alphanumeric characters.
(should|should not): A positive or negative assertion.: “to” can also be used instead of “should”.
<text>: A freeform amount of text.: This will match anything.; Additional Step Arguments: (optional) A table of additional client pod log options.

https://pkg.go.dev/k8s.io/api/core/v1#PodLogOptions

Pod Log Options:
| container     | string  |
| follow        | boolean |
| previous      | boolean |
| since seconds | number  |
| timestamps    | boolean |
| tail lines    | number  |
| limit bytes   | number  |

<assertion> <duration> <reference> logs (should|should not) say <text>