Sometimes you don't want to run all tests and Kotest provides tags to be able to determine which
tests are executed at runtime. Tags are objects inheriting from
For example, to group tests by operating system you could define the following tags:
Alternatively, tags can be defined using the
StringTag class. When using this class, observe the following rules:
- A tag must not be null or blank.
- A tag must not contain whitespace.
- A tag must not contain ISO control characters.
- A tag must not contain any of the following characters:
- !: exclamation mark
- (: left paren
- ): right paren
- &: ampersand
- |: pipe
Test cases can then be marked with tags using the
Then by invoking the test runner with a system property of
kotest.tags you can control which tests are run. The expression to be
passed in is a simple boolean expression using boolean operators:
!, with parenthesis for association.
Tag1 & (Tag2 | Tag3)
Provide the simple names of tag object (without package) when you run the tests. Please pay attention to the use of upper case and lower case! If two tag objects have the same simple name (in different name spaces) they are treated as the same tag.
Example: To run only test tagged with
Linux, but not tagged with
Database, you would invoke
Gradle like this:
Tags can also be included/excluded in runtime (for example, if you're running a project configuration instead of properties) through the
Operators (in descending order of precedence)
|&||and||linux & integration|
||||or||windows | microservice|
You can mark all tests in a spec using the tags function in the spec itself.
If you wish to avoid creating the spec class at all then you can annotate a spec using
Any tags added using this annotation apply to all tests in the class, however this will not stop a class from
being instantiated unless explicitly excluded.
Consider the following example:
|kotest.tags=Linux||yes||yes||A, B, C are executed because all tests inherit the |
|kotest.tags=Linux & Mysql||yes||yes||A is executed only because all tests have the |
|kotest.tags=!Linux||no||no||No tests are executed, and the MyTestClass is not instantiated because we can exclude it based on the tags annotation|
|kotest.tags=!UnitTest||yes||no||No tests are executed because all tests inherit |
|kotest.tags=Mysql||yes||yes||A is executed only, because that is the only test marked with |
|kotest.tags=!Mysql||yes||yes||B, C are executed only, because A is excluded by being marked with |
|kotest.tags=Linux & !Mysql||yes||yes||B, C are executed only, because all tests inherit |
Special attention is needed in your gradle configuration
To use System Properties (-Dx=y), your gradle must be configured to propagate them to the test executors, and an extra configuration must be added to your tests:
Kotlin Gradle DSL:
This will guarantee that the system property is correctly read by the JVM