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

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

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

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.JSONSchema (experimental)

Experimental: This function is experimental and may be enabled with the --experimental flag.

Validates the given value against a JSON Schema, and returns the value unchanged. If the value does not match the schema, template generation fails with a list of every failing location.

The schema can be a JSON string, or already-parsed data such as a datasource. Schemas without a $schema keyword are treated as draft 2020-12; drafts 4, 6, 7 and 2019-09 are also supported.

References within the schema (e.g. #/$defs/name) are supported, but $refs to other files or URLs are not loaded.

Added in gomplate v5.3.0

Usage

test.JSONSchema schema value

value | test.JSONSchema schema

Arguments

Examples

$ gomplate --experimental -i '{{ "hi" | test.JSONSchema `{"type": "string", "maxLength": 3}` }}'
hi

$ cat config.yaml
name: web
replicas: 0
$ gomplate --experimental -d config=config.yaml -d schema=schema.json \
    -i '{{ $c := ds "config" | test.JSONSchema (ds "schema") }}{{ $c.name }}'
template: <arg>:1:27: executing "<arg>" at <test.JSONSchema>: error calling JSONSchema: schema validation failed:
- at '/replicas': minimum: got 0, want 1

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

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

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

Examples

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