Write `zio-kafka-testkit` documentation #846

guizmaii · 2023-05-12T15:48:08Z

Related to #845

The doc can be read here: https://github.com/zio/zio-kafka/blob/testing_doc/docs/writing-tests.md

TODO:

Add ZIOSpecWithKafka doc
use mdoc

docs/writing-tests.md

erikvanoosten

Nice! We really need something like this.
Would you like me to pick up a part of the work? For example, I could write some examples for testing zio-kafka consumers.

docs/writing-tests.md

erikvanoosten · 2023-05-14T12:55:19Z

docs/writing-tests.md

+```
+
+Let's study some simple examples of tests you can write with the `zio-kafka-testkit` and `zio-test`.
+


There are two important techniques for testing zio-kafka apps. One is to produce test data so that we can test a consumer, two is to consume from a topic so that we can test a producer. I would love to see that described in the introduction here.

docs/writing-tests.md

zio-kafka-example/src/test/scala/zio/kafka/example/ProducerSpec.scala

zio-kafka-testkit/src/main/scala/zio/kafka/testkit/embedded/Kafka.scala

guizmaii · 2023-05-14T16:27:56Z

zio-kafka-testkit/src/main/scala/zio/kafka/testkit/KafkaTestUtils.scala

  val producer: ZLayer[Kafka, Throwable, Producer] =
-    (ZLayer.fromZIO(producerSettings) ++ ZLayer.succeed(Serde.string: Serializer[Any, String])) >>>


This ZLayer.succeed(Serde.string: Serializer[Any, String]) was useless

guizmaii · 2023-05-14T16:28:27Z

zio-kafka-testkit/src/main/scala/zio/kafka/testkit/KafkaTestUtils.scala

-    (ZLayer.fromZIO(transactionalProducerSettings) ++ ZLayer.succeed(
-      Serde.string: Serializer[Any, String]
-    )) >>>


This ZLayer.succeed(Serde.string: Serializer[Any, String]) was useless

erikvanoosten

Nice!
Some small remarks but nothing exciting.

erikvanoosten · 2023-05-21T13:38:34Z

docs/writing-tests.md

+The `sequential` aspect from zio-test is used to specify that the tests in the suite must be run sequentially. This is necessary because Kafka is a shared resource.
+We don't want tests to interfere with each other.


It is possible to write your tests such that they do not interfere with each other. Therefore I propose to weaken the text a bit to:

Suggested change

The `sequential` aspect from zio-test is used to specify that the tests in the suite must be run sequentially. This is necessary because Kafka is a shared resource.

We don't want tests to interfere with each other.

The `sequential` aspect from zio-test is used to specify that the tests in the suite must be run sequentially instead of concurrently. Kafka is shared between the tests so running them sequentially prevents tests to influence each other.

I think we're saying the same thing but differently

The original text uses the word 'necessary'. This is strictly not correct because there are other ways to achieve the same goal.

erikvanoosten · 2023-05-21T13:43:20Z

docs/writing-tests.md

+Finally, we annotate the suite with the `timeout` and `sequential` aspects.   
+The `timeout` aspect from zio-test is used to specify a timeout for the entire suite. If the suite takes more than 5 minutes to run, it will fail.    


I propose that we split the paragraph in 2 (add a newline after it will fail):

Suggested change

Finally, we annotate the suite with the `timeout` and `sequential` aspects.

The `timeout` aspect from zio-test is used to specify a timeout for the entire suite. If the suite takes more than 5 minutes to run, it will fail.

Finally, we annotate the suite with the `timeout` and `sequential` aspects.

The `timeout` aspect from zio-test is used to specify a timeout for the entire suite. If the suite takes more than 5 minutes to run, it will fail.

I prefer to keep these things grouped.

The paragraph is structured in 3 parts:

Introduction to the concept we'll study in this paragraph: "Finally, we annotate the suite with the timeout and sequential aspects."

The first concept: "The timeout aspect from zio-test ..."

The second concept: "The sequential aspect from zio-test ..."

docs/writing-tests.md

erikvanoosten · 2023-05-21T13:50:07Z

docs/writing-tests.md

+
+Finally, we use the `KafkaRandom` trait from zio-kafka-testkit and its methods to generate random values for the Consumer client ID, the Consumer group ID and the topic name.     
+More details about this `KafkaRandom` trait [later in this page](#kafkarandom-trait).    
+Using random values for these parameters is important to avoid conflicts between tests as we share one Kafka instance between all the tests of the suite.


Saying we share a Kafka instance is enough, how is less important for this paragraph.

Also, as I have said before, I am not in favor of using random values. I prefer my test parameters to be the same for each run. (With a big exception for property based testing.)

Also, since this text is important, IMHO it should be a new paragraph.

Suggested change

Using random values for these parameters is important to avoid conflicts between tests as we share one Kafka instance between all the tests of the suite.

Using different values for these parameters is important to avoid conflicts between tests as we share one Kafka instance between the tests. Using random values is a convenient way to make sure they are different.

I'd prefer to keep as is

That answer disappoints me a bit. I'd have preferred you tell me where I am wrong.

docs/writing-tests.md

zio-kafka-bench/src/main/scala/zio/kafka/bench/ConsumersComparisonBenchmark.scala

zio-kafka-example/src/main/scala/zio/kafka/example/Main.scala

…ke it more explicit that it's something that can be used by zio-kafka users Also, change the base namespace of this module from `zio.kafka` to `zio.kafka.testkit` to make things more explicit

Co-authored-by: Erik van Oosten <e.vanoosten@grons.nl>

guizmaii force-pushed the testing_doc branch 3 times, most recently from ae20ca3 to 8f775d0 Compare May 12, 2023 15:58

guizmaii commented May 14, 2023

View reviewed changes

docs/writing-tests.md Outdated Show resolved Hide resolved

erikvanoosten reviewed May 14, 2023

View reviewed changes

guizmaii force-pushed the testing_doc branch 2 times, most recently from 89cb239 to 61c8b6a Compare May 14, 2023 16:26

guizmaii commented May 14, 2023

View reviewed changes

guizmaii force-pushed the testing_doc branch 3 times, most recently from c8a80ff to d319dc2 Compare May 14, 2023 17:37

guizmaii marked this pull request as ready for review May 14, 2023 18:01

guizmaii force-pushed the testing_doc branch 3 times, most recently from c0397a4 to 99b3989 Compare May 14, 2023 18:22

guizmaii force-pushed the rename_testkit_module branch from 3c1a2e8 to 2e72287 Compare May 14, 2023 18:24

guizmaii force-pushed the testing_doc branch 7 times, most recently from f8a2597 to 8e9ece8 Compare May 14, 2023 18:53

guizmaii force-pushed the rename_testkit_module branch from 2e72287 to 6bc6ace Compare May 15, 2023 17:48

guizmaii force-pushed the testing_doc branch from 8e9ece8 to 4168a9f Compare May 15, 2023 17:56

guizmaii force-pushed the rename_testkit_module branch from 6bc6ace to e1613c4 Compare May 17, 2023 11:12

guizmaii force-pushed the testing_doc branch 3 times, most recently from 1bc7ae4 to 3b08395 Compare May 20, 2023 06:24

guizmaii force-pushed the testing_doc branch 20 times, most recently from 40bb465 to 95e9fa8 Compare May 20, 2023 07:47

erikvanoosten mentioned this pull request May 21, 2023

Rename the zio-kafka-test-utils module to zio-kafka-testkit && change its base package from zio.kafka to zio.kafka.testkit #845

Merged

erikvanoosten approved these changes May 21, 2023

View reviewed changes

Base automatically changed from rename_testkit_module to master May 21, 2023 17:44

guizmaii added 2 commits May 21, 2023 21:48

Rename the zio-kafka-test-utils module to zio-kafka-testkit to ma…

ccf7e27

…ke it more explicit that it's something that can be used by zio-kafka users Also, change the base namespace of this module from `zio.kafka` to `zio.kafka.testkit` to make things more explicit

Write zio-kafka-testkit documentation

2e59e21

guizmaii force-pushed the testing_doc branch from 95e9fa8 to 2e59e21 Compare May 21, 2023 17:48

Update docs/writing-tests.md

ce441ce

Co-authored-by: Erik van Oosten <e.vanoosten@grons.nl>

guizmaii force-pushed the testing_doc branch from 06df0d4 to ce441ce Compare May 21, 2023 17:57

guizmaii merged commit bf336fc into master May 21, 2023
4 of 11 checks passed

guizmaii deleted the testing_doc branch May 21, 2023 18:11

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Write `zio-kafka-testkit` documentation #846

Write `zio-kafka-testkit` documentation #846

guizmaii commented May 12, 2023 •

edited

erikvanoosten left a comment

erikvanoosten May 14, 2023

guizmaii May 14, 2023

guizmaii May 14, 2023

erikvanoosten left a comment

erikvanoosten May 21, 2023

guizmaii May 21, 2023

erikvanoosten May 21, 2023

erikvanoosten May 21, 2023

guizmaii May 21, 2023

erikvanoosten May 21, 2023

guizmaii May 21, 2023

erikvanoosten May 23, 2023

		```

		Let's study some simple examples of tests you can write with the `zio-kafka-testkit` and `zio-test`.

		val producer: ZLayer[Kafka, Throwable, Producer] =
		(ZLayer.fromZIO(producerSettings) ++ ZLayer.succeed(Serde.string: Serializer[Any, String])) >>>

		The `sequential` aspect from zio-test is used to specify that the tests in the suite must be run sequentially. This is necessary because Kafka is a shared resource.
		We don't want tests to interfere with each other.

		Finally, we annotate the suite with the `timeout` and `sequential` aspects.
		The `timeout` aspect from zio-test is used to specify a timeout for the entire suite. If the suite takes more than 5 minutes to run, it will fail.

	Using random values for these parameters is important to avoid conflicts between tests as we share one Kafka instance between all the tests of the suite.

	Using different values for these parameters is important to avoid conflicts between tests as we share one Kafka instance between the tests. Using random values is a convenient way to make sure they are different.

Write zio-kafka-testkit documentation #846

Write zio-kafka-testkit documentation #846

Conversation

guizmaii commented May 12, 2023 • edited

erikvanoosten left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

erikvanoosten left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Write `zio-kafka-testkit` documentation #846

Write `zio-kafka-testkit` documentation #846

guizmaii commented May 12, 2023 •

edited