Query Language

TQL or Testomat.io Query Language is a flexible way to filter tests data inside Testomat.io. Query Language provides basic selection operators like and, or and not and braces to prioritize selection.

Writing Queries

To access Query Language Editor click on the button right to search field on Tests screen:

TQL Access

This will open an extended TQL editor which allows to write queries in a dedicated interface with some hints provided:

Alt text

A query can select tests by comparing its fields. The basic comparison operators are: == for 'equals' and != for 'not equals'.

The most popular use case would be selecting tests by tag A or by tag B.

This could be written as following query:

tag == 'A' or tag == 'B'

if a test needs to have both tags at once, use and operator:

tag == 'A' and tag == 'B'

In case you want tests with tag A excluding tests that contain tag B, this should be the query:

tag == 'A' and not (tag == 'B')

or the same with !=

tag == 'A' and tag != 'B'

In case you build a complex query use braces () to explicitly set priority of comparison. For instance, to select tests with tag A or tests with both tags B and C, use braces to set priority:

tag == 'A' or (tag == 'B' and tag == 'C')


Use braces when you have combination of and / or operators. Query like A and B or C and D is ambiguous, so it should be rewritten to something like: (A and B) or (C and D) to explicitly set the order of operators.

Please note, that most of variables requires values in string format wrapped into single or double quotes:

tag == A <- won't work !!!

tag == 'A' <- will work

Also, the equality should always be set as ==:

tag = 'A' <- won't work !!!!

tag == 'A' <- will work


In previous section we used tag in the query. tag is an allowed query variable. Here is a comprehenisve list of variables you can use in the query:

tagMatch tests by tagtag == 'important'
labelMatch tests by label or custom fieldlabel == 'Automatable'
label == 'Severity:🔥Critical' (please note that you need to include emojis if you use them as value in custom fields)
priorityMatch tests by prioritypriority >= 'normal'
priority == 'critical'
issueMatch tests by issue as URL or Jira issue keyissue == 'https://github.com/o/r/issues/1'
issue == 'JST-2'
jiraMatch tests by Jira issue keyjira == 'JST-2'
stateMatch tests by automation statestate == 'automated'
state == 'manual'
state == 'sync'
state == 'unsync'
statusMatch tests by run statusstatus == 'passed'
status == 'failed'
created_atMatch tests by creation datecreated_at >= 3.days_ago
created_at < 1.month_ago
created_at == today()
created_at <= '2023-12-31'
updated_atMatch tests by last updateupdated_at >= 3.days_ago
updated_at <= '2023-12-31'
run_atMatch tests by last execution daterun_at < 1.week_ago
run_at == today()
created_byMatch tests by author's namecreated_by == 'Antonio Primus'
assigned_toMatch tests by assignee's nameassigned_to == 'Antonio Primus'
suiteMatch tests inside a folder or suitesuite % 'Checkout'
suite == '{SUITE_ID}'
testMatch tests by title or IDtest % 'User login'
test == '{TEST_ID}'

Filter By Priority

Priority variable allow additional comparisons operators to be used > < >=, <=. So you can select tests with a priority higher than normal:

priority > 'normal'

Filter By Title

To match test by its title or its suite title a special operator % was introduced. This allows to match all tests containing a text inside its title. For instance, this query will match all tests with word User in their title:

test % 'User'

Searched text should be longer than 4 chars.

This also works for suites, so you can select all tests from a suite containing User word:

suite % 'User'

However, if there are multiple suites with word User in their title, only the first suite will be selected.


When you deal with date variables like created_at, run_at, and others you can set absolute date in YYYY-MM-DD format or use functions like days_ago, weeks_ago, months_ago to specify a date from now.





There is also today() function that can be used to specify current date. For instance, to list all tests created today use this query:

created_at == today()

To list all tests created for the previous week use 1.week_ago with > operator:

created_at > 1.week_ago

To list all tests that were executed more than 1 month ago use 1.month_ago with < operator:

run_at < 1.month_ago


Variables like assigned_to or created_by require user names to be passed as value. For instance, this will select all tests created by John Snow.

created_by == 'John Snow'

Filtering always happens by user name, not by email or user ID. Also, user should exist inside the project.