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.

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.

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.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.

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!

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