How to test an application¶
ksqlDB 0.30 ships with a new sql-based testing tool (
run-ksql-test). For documentation on the old test runner,
switch to an older version of this page.
ksqlDB ships with a command line tool to test KSQL statements automatically. It doesn't require an active Apache Kafka® or ksqlDB cluster.
To test a set of KSQL statements, provide a folder containing the sql test files and another folder that the testing tool will use to store temporary files.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
Here is a sample test file:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
A test file contains one or more tests separated by the
Each test consists of comments containing directives and sql stataments.
There are three directives available:
--@test: name of test. Required in every test.
[email protected]: error class. Checks that the test throws an error of the provided type.
[email protected]: error message. Checks that the test throws an error with a message containing the provided message.
run-ksql-test runs each statement in a test sequentially until an error is thrown or the end of
the test is reached.
The following are the supported KSQL statements in
CREATE STREAM AS SELECT
CREATE TABLE AS SELECT
There are also four test only statements for verifying data.
Asserts the existence of a stream with the given elements and properties.
Asserts the existence of a table with the given elements and properties.
Asserts that a row with the given values is in a source.
Asserts that a tombstone is in a source.
run-ksql-test indicates the success or failure of a test by
printing the corresponding record. The following is the result of a
Your output should resemble:
1 2 3
Note that the tool may also write verbose log output to the terminal too, in which case you may need to page through it to locate the test status message.
If a test fails, the testing tool will indicate the failure along with the cause. Here is an example of the output for a failing test:
1 2 3 4 5 6 7 8 9
The tool will return an exit code of
1 if any test fails and
0 if all tests pass.
run-ksql-test doesn't use a real Kafka cluster. Instead, it simulates
the behavior of a cluster with a single broker for the KSQL queries. This
means that the testing tool ignores configuration settings for the input
and output topics, like the number of partitions or replicas.