Skip to content

Commit 6fd9e83

Browse files
committed
+tck explains createElement in more useful terms
resolves #231
1 parent 5fa310d commit 6fd9e83

File tree

1 file changed

+8
-2
lines changed

1 file changed

+8
-2
lines changed

tck/README.md

+8-2
Original file line numberDiff line numberDiff line change
@@ -243,11 +243,17 @@ Subscriber rules Verification is split up into two files (styles) of tests.
243243

244244
The Blackbox Verification tests do not require the implementation under test to be modified at all, yet they are *not* able to verify most rules. In Whitebox Verification, more control over `request()` calls etc. is required in order to validate rules more precisely.
245245

246+
It is highly recommended to implement the `SubscriberBlackboxVerification<T>` instead of the blackbox one even if it is more troublesome to do so, as it can test far more corner cases in implementations that would otherwise be left untested (if only blackbox tests would be used).
247+
246248
### createElement and Helper Publisher implementations
247249
Since testing a `Subscriber` is not possible without a corresponding `Publisher` the TCK Subscriber Verifications
248250
both provide a default "*helper publisher*" to drive its test and also alow to replace this Publisher with a custom implementation.
249251
The helper publisher is an asynchronous publisher by default - meaning that your subscriber can not blindly assume single threaded execution.
250252

253+
When extending subscriber verification classes a type parameter representing the element type passed through the stream must be given. MostImplementations usually should not be sensitive to the type of element being signalled, but sometimes a Subscriber may be limited to only be able to work within a known set of types - like a `FileSubscriber extends Subscriber<String>` for example, that writes each element it receives as new line into a file.
254+
For element type agnostic Subscribers it is the simplest to parameterize the tests using `Integer` and in the `createElement(int idx)` method (explained below in futher detail), return the incoming `int`.
255+
In case an implementation needs to work on a specific type, the verification class should be parameterized using that type (e.g. `class StringSubTest extends SubscriberBlackboxVerification<String>`) and a `String` must be returned from the `createElement` method.
256+
251257
While the `Publisher` implementation is provided, creating the signal elements is not – this is because a given Subscriber
252258
may for example only work with `HashedMessage` or some other specific kind of signal. The TCK is unable to generate such
253259
special messages automatically, so we provide the `T createElement(Integer id)` method to be implemented as part of
@@ -268,8 +274,8 @@ public class MySubscriberTest extends SubscriberBlackboxVerification<Integer> {
268274
```
269275

270276

271-
The `createElement` method MAY be called from multiple
272-
threads, so in case of more complicated implementations, please be aware of this fact.
277+
The `createElement` method MAY be called from multiple threads, so in case of more complicated implementations,
278+
please be aware of this fact.
273279

274280
**Very Advanced**: While we do not expect many implementations having to do so, it is possible to take full control of the `Publisher`
275281
which will be driving the TCKs test. This can be achieved by implementing the `createHelperPublisher` method in which you can implement your

0 commit comments

Comments
 (0)