test functions

The test namespace contains some simple functions to help validate assumptions and can cause template generation to fail in specific cases.

test.Assert

Alias: assert

Asserts that the given expression or value is true. If it is not, causes template generation to fail immediately with an optional message.

Added in gomplate v2.7.0

Usage

test.Assert [message] value
value | test.Assert [message]

Arguments

name description
message (optional) The optional message to provide in the case of failure
value (required) The value to test

Examples

$ gomplate -i '{{ assert (eq "foo" "bar") }}'
template: <arg>:1:3: executing "<arg>" at <assert (eq "foo" "ba...>: error calling assert: assertion failed
$ gomplate -i '{{ assert "something horrible happened" false }}'
template: <arg>:1:3: executing "<arg>" at <assert "something ho...>: error calling assert: assertion failed: something horrible happened

test.Fail

Alias: fail

Cause template generation to fail immediately, with an optional message.

Added in gomplate v2.7.0

Usage

test.Fail [message]
message | test.Fail

Arguments

name description
message (optional) The optional message to provide

Examples

$ gomplate -i '{{ fail }}'
template: <arg>:1:3: executing "<arg>" at <fail>: error calling fail: template generation failed
$ gomplate -i '{{ test.Fail "something is wrong!" }}'
template: <arg>:1:7: executing "<arg>" at <test.Fail>: error calling Fail: template generation failed: something is wrong!

test.IsKind

Alias: isKind

Report whether the argument is of the given Kind. Can be used to render different templates depending on the kind of data.

See the Go reflect source code for the complete list, but these are some common values:

  • string
  • bool
  • int, int64, uint64
  • float64
  • slice
  • map
  • invalid (a catch-all, usually just nil values)

In addition, the special kind number is accepted by this function, to represent any numeric kind (whether float32, uint8, or whatever). This is useful when the specific numeric type is unknown.

See also test.Kind.

Added in gomplate v3.8.0

Usage

test.IsKind kind value
value | test.IsKind kind

Arguments

name description
kind (required) the kind to compare with (see description for possible values)
value (required) the value to check

Examples

$ gomplate -i '{{ $data := "hello world" }}
{{- if isKind "string" $data }}{{ $data }} is a string{{ end }}'
hello world is a string

$ gomplate -i '{{ $object := dict "key1" true "key2" "foobar" }}
{{- if test.IsKind "map" $object }}
Got a map:
{{ range $key, $value := $object -}}
  - "{{ $key }}": {{ $value }}
{{ end }}
{{ else if test.IsKind "number" $object }}
Got a number: {{ $object }}
{{ end }}'

Got a map:
- "key1": true
- "key2": foobar

test.Kind

Alias: kind

Report the kind of the given argument. This differs from the type of the argument in specificity; for example, while a slice of strings may have a type of []string, the kind of that slice will simply be slice.

If you need to know the precise type of a value, use printf "%T" $value.

See also test.IsKind.

Added in gomplate v3.8.0

Usage

test.Kind value
value | test.Kind

Arguments

name description
value (required) the value to check

Examples

$ gomplate -i '{{ kind "hello world" }}'
string

$ gomplate -i '{{ dict "key1" true "key2" "foobar" | test.Kind }}'
map

test.Required

Alias: required

Passes through the given value, if it’s non-empty, and non-nil. Otherwise, exits and prints a given error message so the user can adjust as necessary.

This is particularly useful for cases where templates require user-provided data (such as datasources or environment variables), and rendering can not continue correctly.

This was inspired by Helm’s required function, but has slightly different behaviour. Notably, gomplate will always fail in cases where a referenced key is missing, and this function will have no effect.

Added in gomplate v3.0.0

Usage

test.Required [message] value
value | test.Required [message]

Arguments

name description
message (optional) The optional message to provide when the required value is not provided
value (required) The required value

Examples

$ FOO=foobar gomplate -i '{{ getenv "FOO" | required "Missing FOO environment variable!" }}'
foobar
$ FOO= gomplate -i '{{ getenv "FOO" | required "Missing FOO environment variable!" }}'
error: Missing FOO environment variable!

$ cat <<EOF> config.yaml
defined: a value
empty: ""
EOF
$ gomplate -d config=config.yaml -i '{{ (ds "config").defined | required "The `config` datasource must have a value defined for `defined`" }}'
a value
$ gomplate -d config=config.yaml -i '{{ (ds "config").empty | required "The `config` datasource must have a value defined for `empty`" }}'
template: <arg>:1:25: executing "<arg>" at <required "The `confi...>: error calling required: The `config` datasource must have a value defined for `empty`
$ gomplate -d config=config.yaml -i '{{ (ds "config").bogus | required "The `config` datasource must have a value defined for `bogus`" }}'
template: <arg>:1:7: executing "<arg>" at <"config">: map has no entry for key "bogus"

test.Ternary

Alias: ternary

Returns one of two values depending on whether the third is true. Note that the third value does not have to be a boolean - it is converted first by the conv.ToBool function (values like true, 1, "true", "Yes", etc… are considered true).

This is effectively a short-form of the following template:

{{ if conv.ToBool $condition }}{{ $truevalue }}{{ else }}{{ $falsevalue }}{{ end }}

Keep in mind that using an explicit if/else block is often easier to understand than ternary expressions!

Added in gomplate v3.1.0

Usage

test.Ternary truevalue falsevalue condition
condition | test.Ternary truevalue falsevalue

Arguments

name description
truevalue (required) the value to return if condition is true
falsevalue (required) the value to return if condition is false
condition (required) the value to evaluate for truthiness

Examples

$ gomplate -i '{{ ternary "FOO" "BAR" false }}'
BAR
$ gomplate -i '{{ ternary "FOO" "BAR" "yes" }}'
FOO