Skip to content

Commit

Permalink
docs: Minor improvements to testing tool docs (#6241)
Browse files Browse the repository at this point in the history
* Add file generation tip

* Fix headings to make them flow better

* Add line breaks at col80
  • Loading branch information
Robin Moffatt authored Sep 17, 2020
1 parent 25deb4a commit 8cfb46b
Showing 1 changed file with 32 additions and 1 deletion.
33 changes: 32 additions & 1 deletion docs/developer-guide/test-and-debug/ksqldb-testing-tool.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,23 @@ the previous test:
}
```

#### Generating input files automagically from existing topic data

You can use [`kafkacat`](https://github.com/edenhill/kafkacat) and
[`jq`](https://stedolan.github.io/jq/) in combination to create an input file
based on data already in a Kafka topic:

```bash
kafkacat -b broker:29092 -t my_topic -C -e -J | \
jq --slurp '{inputs:[.[]|{topic:.topic,timestamp: .ts, key: .key, value: .payload|fromjson}]}' \
> input.json
```

Replace `broker:29092` with your broker host and port, and `my_topic` with the
name of your topic. You can limit how many messages are written to the file by
adding a `-c` flag to the `kafkacat` statement—for example, `-c42` would write
the first 42 messages from the topic.

### Output File

The output file is a JSON file with an array field named `outputs`.
Expand Down Expand Up @@ -135,6 +152,17 @@ a window field:
Currently, in the input files you can have only records with session
window types.

#### Generating output files automagically from existing topic data

You can use a similar approach to that shown above for generating input files,
but be aware that it won't handle time windows in cases where these are
required. In the case of aggregates it will often only have the final value,
and not every intermediate value that is generated by the testing tool due to
buffering (see discussion in "Input Consumption" below).

Running the testing tool
------------------------

The testing tool indicates the success or failure of a test by
printing the corresponding message. The following is the result of a
successful test:
Expand All @@ -146,9 +174,12 @@ ksql-test-runner -s statements.sql -i input.json -o output.json
Your output should resemble:

```
Test passed!
>>> Test passed!
```

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:

Expand Down

0 comments on commit 8cfb46b

Please sign in to comment.