Dedicated example

[pihme]

Background

Initially we wanted to use our own tests also as examples to avoid duplicating code. However, our own tests are not ideal as examples:

• They are implemented once and then run against different test engine implementations in different versions, which is hard to understand, and also not necessary to understand by users
• They include logic that is based on interpreting the log records returned by the engine. This is common in our tests, but not how we recommend users to write their tests
• They are exhaustive, but often only include a single assertion

We also have a more complex tests, which uses different assertions in combination. But this test was hard to find among all the other files and also suffered from aforementioned problems.

Change

This PR

• introduces a new module examples and advertises it in the readme
• Moved the complex test into that new module so that it stands out more
• Inlined code so that the test is only a single file
• Added comments to explain details in the test which are less obvious
• Rewrote those parts of the code that used exported records to only use Zeebe Client API commands

Related issues

closes #367

Definition of Done

Code changes:

• The changes are backwards compatibility with previous versions
• If it fixes a bug then PRs are created to backport the fix

Testing:

• There are unit/integration tests that verify all acceptance criterias of the issue
• New tests are written to ensure backwards compatibility with further versions
• The behavior is tested manually

Documentation:

• Javadoc has been written
• The documentation is updated

[github-actions]

Unit Test Results

  47 files    47 suites   1m 37s ⏱️
107 tests 107 ✔️ 0 💤 0 ❌
340 runs  340 ✔️ 0 💤 0 ❌

Results for commit 4583307.

♻️ This comment has been updated with latest results.

[saig0]

@pihme I like it 👍 Good job 🎉