CEL expressions in configuration files
A YAML or JSON configuration file can't contain JavaScript functions. Instead, the options that take a function in a JavaScript configuration file, and some others, accept an expression written in CEL (Common Expression Language) and wrapped in ${{ ... }}. With expressions, a static configuration file can filter tests, match categories and environments, compute names, and read environment variables.
Syntax
name: "${{ 'Nightly ' + date.isoDate }}"
plugins:
awesome:
options:
filter: "${{ test.status != 'skipped' }}"{
"name": "${{ 'Nightly ' + date.isoDate }}",
"plugins": {
"awesome": {
"options": {
"filter": "${{ test.status != 'skipped' }}"
}
}
}
}- The whole value must be one expression. A value with text before
${{is used as plain text, and a value with text after}}is an error. - Write strings inside an expression in single quotes, and quote the whole value in YAML. For a long expression, use a YAML folded block (
>-), which can span several lines. - Frequently used operators and functions:
==,!=,<,>,&&,||,!,condition ? a : b,+(also joins strings),contains(),startsWith(),endsWith(),matches(),list.exists(x, condition),int(),double()andstring(). See the CEL language definition for all of them. matches()checks a regular expression. It is case-sensitive and finds the pattern anywhere in the value, unless you anchor it with^and$. Double the backslashes in the pattern, for examplename.matches('^internal_\\d+$'). In a double-quoted YAML string, double them once more (\\\\d), or use a>-block, which doesn't need that.- Check optional values with
has()before you use them: environment variables that may not be set, and test result fields that may be missing, such asdurationor the error message. For example,has(env.CI) && env.CI == 'true'. Reading a missing value is an error. - Allure checks the expressions when it reads the configuration file. If an expression is invalid or returns a value of the wrong type, Allure stops with an error that names the option, for example,
Invalid expression at hideLabels[0]: expression must return a boolean.
Expressions also work in JavaScript configuration files, but there you can use functions instead.
Where you can use expressions
| Option | Variables | The expression returns |
|---|---|---|
hideLabels items | name | boolean: true hides the label |
categories matchers | data | boolean: true puts the test in the category |
environments.<id>.matcher | labels | boolean: true puts the test in the environment |
name, environments.<id>.name, category name, reportName of the Awesome, Classic, Dashboard and Allure2 plugins, Awesome charts[].title, Dashboard layout[].title, CSV fields[].header, TestOps launchName | env, date | string |
filter of the Awesome, Classic, Dashboard, CSV, Log and TestOps plugins | test, env | boolean: true includes the test |
Log qualityGateFilter | result, env | boolean: true prints the quality gate result |
CSV fields[].accessor | test, env | string, or null for an empty cell |
CSV sort | a, b, env | number: negative if a goes first, positive if b does |
qualityGate enabled | env | boolean |
Expected values of the qualityGate rules | env | the value the rule expects, for example a number |
filter of the qualityGate rule sets | test, env | boolean: true checks the test |
message and successMessage in qualityGate.use | expected, actual | string |
allureService.accessToken | env | string |
Allure takes the values of all other options literally. For example, the filter option of the TestPlan plugin still needs a JavaScript configuration file.
The variables contain:
env- the environment variables. Allure reads them once, when it reads the configuration file.date- the time when Allure read the configuration file, in UTC:date.iso(for example,2026-11-06T09:30:00.000Z),date.isoDate(2026-11-06),date.year,date.month(1 to 12),date.dayanddate.unixMs(milliseconds since the Unix epoch).test,a,b- a test result, with fields such asname,fullName,status,duration(in milliseconds),flaky,labels(a list of objects withnameandvalue),parameters,error.messageanderror.trace.data- the data a category matcher checks:status,flaky,labelsand, if available,message,trace,duration(in milliseconds),transitionandenvironment.labels- the labels of the test result, a list of objects withnameandvalue.name- the name of the label.result- a quality gate result, with therule,success,actual,expectedandmessagefields.expected,actual- the value that the quality gate rule expects and the value it found.
Examples
The examples below are parts of one configuration file.
Report name
The report name includes the date when the report was generated. If the REPORT_NAME environment variable is set, the name starts with its value, otherwise with "Allure Report":
name: "${{ (has(env.REPORT_NAME) ? env.REPORT_NAME : 'Allure Report') + ' ' + date.isoDate }}"A name passed with the --name command-line option replaces the configured name and is used as is.
Hide labels
Hide the owner label, and all labels whose names start with internal_:
hideLabels:
- owner
- "${{ name.startsWith('internal_') }}"Categories
The first category collects the tests whose error message contains "timeout". The second one collects the failed UI tests that ran for longer than 5 seconds:
categories:
- name: Timeouts
matchers: "${{ has(data.message) && data.message.contains('timeout') }}"
- name: Slow UI failures
matchers: >-
${{ data.status == 'failed' && has(data.duration) && data.duration > 5000 &&
data.labels.exists(l, l.name == 'layer' && l.value == 'ui') }}If the name of a category is an expression, set the category's id, so that the category stays the same when its name changes.
Environments
Put the tests that ran in Firefox on Linux into one environment, and the tests that ran in Chrome into another:
environments:
firefox_linux:
name: Firefox on Linux
matcher: >-
${{ labels.exists(l, l.name == 'browser' && l.value == 'firefox') &&
labels.exists(l, l.name == 'os' && l.value == 'linux') }}
chrome:
name: Chrome
matcher: "${{ labels.exists(l, l.name == 'browser' && l.value == 'chrome') }}"Filter tests in reports
The Awesome report leaves out skipped tests. The CSV file lists only failed and broken tests, sorted by duration (the longest first), with a computed duration column and the error message. The Log plugin prints only failed and broken tests:
plugins:
awesome:
options:
filter: "${{ test.status != 'skipped' }}"
csv:
options:
fileName: failures.csv
filter: "${{ test.status == 'failed' || test.status == 'broken' }}"
fields:
- header: Name
accessor: name
- header: Duration
accessor: "${{ has(test.duration) ? dyn(string(test.duration) + ' ms') : null }}"
- header: Error
accessor: "${{ has(test.error) && has(test.error.message) ? test.error.message : null }}"
sort: "${{ (has(b.duration) ? b.duration : 0) - (has(a.duration) ? a.duration : 0) }}"
log:
options:
filter: "${{ test.status == 'failed' || test.status == 'broken' }}"Quality gate
The quality gate runs only if the CI environment variable is set, as it is in most CI services. The first rule set allows 5 failed tests, or as many as the MAX_FAILURES environment variable says. The second rule set stops the run as soon as a test with the critical severity fails. The use list changes the message of the maxFailures rule:
qualityGate:
enabled: "${{ has(env.CI) }}"
rules:
- maxFailures: "${{ has(env.MAX_FAILURES) ? int(env.MAX_FAILURES) : 5 }}"
- id: critical
maxFailures: 0
fastFail: true
filter: "${{ test.labels.exists(l, l.name == 'severity' && l.value == 'critical') }}"
use:
- rule: maxFailures
message: "${{ 'Failed tests: ' + string(actual) + ', allowed: ' + string(expected) }}"If you add use, it replaces the list of rules that Allure knows, so list every rule that your rule sets use. For a built-in rule, its name is enough.
When the quality gate is disabled, allure quality-gate skips the check and exits with code 0.
Access token from an environment variable
Read the Allure Report Storage access token from the ALLURE_SERVICE_TOKEN environment variable. You can choose any variable name:
allureService:
accessToken: "${{ has(env.ALLURE_SERVICE_TOKEN) ? env.ALLURE_SERVICE_TOKEN : '' }}"If the variable isn't set, the expression returns an empty string, and Allure works without the storage service. To make the token required, write "${{ env.ALLURE_SERVICE_TOKEN }}": then every Allure command that reads the configuration file stops with an error if the variable isn't set.