Test Workflows Parameterization
Test Workflows parameterization allows you to supply runtime parameters that make your workflows flexible and reusable. You can provide these parameters in two primary ways:
- Configuration Parameters (
config
): Define parameters in your workflow schema that are available via the{{ config.<parameter> }}
syntax. - Environment Parameters (
env
): Pass parameters as environment variables to your container. These variables are injected at runtime and can be referenced dynamically (for example, in shell commands) using the{{ env.<parameter> }}
syntax.
For detailed information on our expression language—including operators, built-in functions, and variables—please see Test Workflows - Expressions.
Overview
Test Workflows support parameterization by allowing you to provide runtime parameters that control various aspects of your workflow. These parameters can be defined as configuration parameters (config
) or supplied as environment parameters (env
). By referencing these parameters using the {{ }}
syntax, you can customize commands, paths, and more—without hardcoding values.
Important: Environment parameters are injected into the container at runtime. They are accessible dynamically (e.g., in shell commands) but cannot be used in static fields such as the container’s
image
.
Using Configuration Parameters (config
)
Defining Configuration Parameters
Configuration parameters are declared in the spec.config
section of your Test Workflow using an OpenAPI-like schema. They specify the type, default values, and whether a parameter is sensitive. Parameters without default values are required.
spec:
config:
version:
type: string
default: "1.32.3"
workers:
type: integer
default: 2
sensitive: true # <- Marked as sensitive
printTree:
type: boolean # <- No default, marked as required
Example: Parametrized Container Image and Commands
In the example below, configuration parameters are used to set the container image version and determine the number of workers for a shell command:
spec:
content:
git:
uri: "https://github.com/kubeshop/testkube"
paths:
- "test/playwright/executor-tests/playwright-project"
container:
image: "mcr.microsoft.com/playwright:v{{ config.version }}" # <- Using config parameter for version
workingDir: "/data/repo/test/playwright/executor-tests/playwright-project"
steps:
- shell: "npm ci && npx playwright test --workers {{ config.workers }}" # <- Using config parameter for workers
- condition: "config.printTree"
shell: "tree /data/repo"
Using Environment Parameters (env
)
Environment parameters are passed to your container at runtime. They are injected dynamically and can be referenced in commands (e.g., shell
) using the {{ env.<parameter> }}
syntax.
Static Environment Parameters
Below is an example of a statically defined environment variable. In this case, the variable is used within a shell command:
spec:
container:
env:
- name: MY_STATIC_VAR
value: "staticValue" # <- Hardcoded static environment variable
steps:
- shell: "echo The static value is {{ env.MY_STATIC_VAR }}" # <- Referencing the env variable in a shell command
Using ConfigMaps with Environment Parameters
You can source environment parameters from Kubernetes ConfigMaps using standard Kubernetes syntax:
spec:
container:
env:
- name: MY_CONFIG_VAR
valueFrom:
configMapKeyRef:
name: your-configmap-name # <- Name of the ConfigMap
key: key-in-configmap # <- Key within the ConfigMap
steps:
- shell: "echo The ConfigMap value is {{ env.MY_CONFIG_VAR }}" # <- Referencing the ConfigMap value
Using Secrets with Environment Parameters
Similarly, environment parameters can be sourced from Kubernetes Secrets:
spec:
container:
env:
- name: MY_SUPER_SECRET
valueFrom:
secretKeyRef:
name: your-secret-name # <- Name of the Kubernetes Secret
key: key-in-secret # <- Key within the Secret
steps:
- shell: |
echo "Secret value: {{ env.MY_SUPER_SECRET }}" # <- Referencing the secret in a shell command
echo "Sanitized secret: {{ shellquote(env.MY_SUPER_SECRET) }}" # <- Using the shellquote function to sanitize output
Combining config
and env
For enhanced flexibility, you can combine configuration parameters with environment parameters. This allows you to define parameters in config
and then inject them into your container as environment variables.
spec:
config:
databaseURL:
type: string
default: "https://default.database.url" # <- Default database URL
container:
env:
- name: DB_URL
value: "{{ config.databaseURL }}" # <- Passing config parameter to an env variable
steps:
- shell: "echo Database URL is {{ env.DB_URL }}" # <- Using the env variable in a shell command
Using Expressions with Parameters
Our expression language allows you to create dynamic expressions using both configuration and environment parameters. You can perform arithmetic, logic, string operations, and more. For example:
# Example: Using math in a condition
condition: 'config.workers > 1 || config.force' # <- Evaluates condition based on config parameters
# Example: Using a built-in function to sanitize output in a shell command
- shell: "echo {{ shellquote(env.MY_SUPER_SECRET) }}" # <- Sanitizes secret before output
You can also build more complex expressions—leveraging JSON-native syntax, arithmetic operators, ternary conditions, and built-in functions such as string
, join
, split
, etc. For a comprehensive overview of available operators, functions, and built-in variables, please refer to Test Workflows - Expressions.
Specifying Parameter Values at Runtime
When executing Test Workflows, you can supply parameter values in several ways:
Running in the UI
When you click Run now in the UI, you will be prompted to enter values for any required configuration parameters.
Running with the CLI
You can also pass parameter values via the CLI using the --config
flag. For environment or secret parameters, use the --env-var
or --global-var
options.
Providing Parameters to Referenced Workflows
Test Workflows can reference other workflows using the execute
step. This feature allows you to trigger a referenced workflow run with specific configuration parameter values. For example, you can provide different values (like the number of workers or version) when triggering each referenced workflow:
spec:
steps:
- execute:
workflows:
- name: "overview--example-13"
config:
workers: 2 # <- Providing workers parameter for the referenced workflow
- name: "overview--example-13"
config:
workers: 4 # <- Different workers parameter
- name: "overview--example-13"
config:
version: "1.23.4" # <- Providing version parameter
In this setup, the execute
step triggers multiple runs of the referenced workflow with the specified configuration parameters. Learn more about Advanced Workflow Orchestration.
By using Test Workflows parameterization, you can easily manage and supply runtime parameters—whether through configuration parameters (config
), environment parameters (env
), or a combination of both. This approach allows you to build flexible, secure, and maintainable workflows that adapt to your runtime needs. For more details on the expression language features available for constructing these parameters, please visit Test Workflows - Expressions.