diff --git a/tck/README.md b/tck/README.md index cf687b71..b401417e 100644 --- a/tck/README.md +++ b/tck/README.md @@ -112,10 +112,11 @@ In order to inform the TCK your Publisher is only able to signal up to `2` eleme } ``` -The TCK also supports Publishers which are not able to signal completion. For example you might have a Publisher being backed by a timer. -Such Publisher does not have a natural way to "complete" after some number of ticks. It would be possible to implement a Processor which would -"take n elements from the TickPublisher and then signal completion to the downstream", but this adds a layer of indirection between the TCK and the -Publisher we initially wanted to test. We suggest testing such unbouded Publishers either way - using a "TakeNElementsProcessor" or by informing the TCK +The TCK also supports Publishers which are not able to signal completion. For example you might have a Publisher being +backed by a timer. Such Publisher does not have a natural way to "complete" after some number of ticks. It would be +possible to implement a Processor which would "take n elements from the TickPublisher and then signal completion to the +downstream", but this adds a layer of indirection between the TCK and the Publisher one initially wanted to test. +It is suggested to test such unbouded Publishers either way - using a "TakeNElementsProcessor" or by informing the TCK that the publisher is not able to signal completion. The TCK will then skip all tests which require `onComplete` signals to be emitted. In order to inform the TCK that your Publiher is not able to signal completion, override the `maxElementsFromPublisher` method like this: @@ -261,12 +262,13 @@ In case an implementation needs to work on a specific type, the verification cla While the `Publisher` implementation is provided, creating the signal elements is not – this is because a given Subscriber may for example only work with `HashedMessage` or some other specific kind of signal. The TCK is unable to generate such -special messages automatically, so we provide the `T createElement(Integer id)` method to be implemented as part of +special messages automatically, so the TCK provides the `T createElement(Integer id)` method to be implemented as part of Subscriber Verifications which should take the given ID and return an element of type `T` (where `T` is the type of elements flowing into the `Subscriber`, as known thanks to `... extends SubscriberWhiteboxVerification`) representing an element of the stream that will be passed on to the Subscriber. -The simplest valid implemenation is to return the incoming `id` *as the element* in a verification using `Integer`s as element types: +The simplest valid implemenation is to return the incoming `id` *as the element* in a verification using `Integer`s as +element types: ```java public class MySubscriberTest extends SubscriberBlackboxVerification { @@ -282,13 +284,13 @@ public class MySubscriberTest extends SubscriberBlackboxVerification { The `createElement` method MAY be called concurrently from multiple threads, so in case of more complicated implementations, please be aware of this fact. -**Very Advanced**: While we do not expect many implementations having to do so, it is possible to take full control of the `Publisher` -which will be driving the TCKs test. This can be achieved by implementing the `createHelperPublisher` method in which you can implement your -own Publisher which will then be used by the TCK to drive your Subscriber tests: +**Very Advanced**: While it is not expected for many implementations having to do so, it is possible to take full +which will be driving the TCKs test. This can be achieved by implementing the `createHelperPublisher` method in which one can implement the +`createHelperPublisher` method by returning a custom Publisher implementation which will then be used by the TCK to drive your Subscriber tests: ```java @Override public Publisher createHelperPublisher(long elements) { - return new Publisher() { /* IMPL HERE */ }; + return new Publisher() { /* CUSTOM IMPL HERE */ }; } ``` @@ -439,11 +441,14 @@ Note that hard-coded values *take precedence* over environment set values (!). ## Subscription Verification -Please note that while `Subscription` does **not** have it's own test class, it's rules are validated inside of the `Publisher` and `Subscriber` tests – depending if the Rule demands specific action to be taken by the publishing, or subscribing side of the subscription contract. +Please note that while `Subscription` does **not** have it's own test class, it's rules are validated inside of the +`Publisher` and `Subscriber` tests – depending if the Rule demands specific action to be taken by the publishing, or +subscribing side of the subscription contract. ## Identity Processor Verification -An `IdentityProcessorVerification` tests the given `Processor` for all `Subscriber`, `Publisher` as well as `Subscription` rules. Internally the `WhiteboxSubscriberVerification` is used for `Subscriber` rules. +An `IdentityProcessorVerification` tests the given `Processor` for all `Subscriber`, `Publisher` as well as +`Subscription` rules. Internally the `WhiteboxSubscriberVerification` is used for `Subscriber` rules. ```java package com.example.streams; @@ -502,12 +507,14 @@ public class MyIdentityProcessorVerificationTest extends IdentityProcessorVerifi The additional configuration options reflect the options available in the Subscriber and Publisher Verifications. -The `IdentityProcessorVerification` also runs additional sanity verifications, which are not directly mapped to Specification rules, but help to verify that a Processor won't "get stuck" or face similar problems. Please refer to the sources for details on the tests included. +The `IdentityProcessorVerification` also runs additional sanity verifications, which are not directly mapped to +Specification rules, but help to verify that a Processor won't "get stuck" or face similar problems. Please refer to the +sources for details on the tests included. ## Ignoring tests -Since you inherit these tests instead of defining them yourself it's not possible to use the usual `@Ignore` annotations to skip certain tests -(which may be perfectly reasonable if your implementation has some know constraints on what it cannot implement). We recommend the below pattern -to skip tests inherited from the TCK's base classes: +Since you inherit these tests instead of defining them yourself it's not possible to use the usual `@Ignore` annotations +to skip certain tests (which may be perfectly reasonable if your implementation has some know constraints on what it +cannot implement). We recommend the below pattern to skip tests inherited from the TCK's base classes: ```java package com.example.streams; @@ -561,6 +568,22 @@ public class MyIdentityProcessorTest extends IdentityProcessorVerification