doc update

Author: mtumilowicz

README.txt

@@ -11,6 +11,14 @@
  * https://docs.spring.io/spring-framework/docs/4.3.15.RELEASE/spring-framework-reference/html/aop.html
  * https://dotty.epfl.ch/docs/reference/new-types/polymorphic-function-types.html
 
+## preface
+
+* task1: create generator of Account
+ * then derive it using zio-test/magnolia
+* task2: derive generator of Contributor
+ * then switch it to generate Contributor from file `src/test/resources/contributors.txt`
+* task3: create and plug aspect to set specific seed (TestSeed.seed) before each test
+
 ## aspect oriented programming
 * lib: caliban
  * example
@@ -133,112 +141,87 @@
  * timeout(60s) @@ repeat(10)
 
 ## property based testing
-* example
+* example: ZIO test
  ```
  test("encode and decode is an identity") {
+ // check operator, one or more generators, assertion
  check(genEvents) { event =>
  assert(decode(encode(event)))(equalTo(event))
  }
  }
  ```
-* support for random and deterministic property based testing
-* integrated shrinking
-* Property based testing is an approach to testing where the framework generates test cases for us instead of having to come up with test cases ourselves.
-* The obvious advantage of property based testing is that it allows us to quickly test a large number of test cases, potentially revealing counterexamples that might not have been obvious.
-* Property based tests typically only generate one hundred to two hundred test cases. In contrast, even a single Int can take on more than a billion different values.
-* If we are generating more complex data types the number of possibilities increases exponentially
- * So in most real world applications of property based testing are only testing a very small portion of the sample space.
- * if counterexamples require multiple generated values to take on very specific values then we may not generate an appropriate counterexample even though such a counterexample does exist
- * A solution to this is to complement property based testing with traditional tests for particular degenerate cases identified by developers.
-* A good generator should also be general enough to generate test cases covering the full range of values over which we expect the property to hold.
- * For example, a common mistake would be to test a form that validates user input with a generator of ASCII characters.
- * This is probably very natural for many of us to do, but what happens if the user input is in Mandarin?
-* In ZIO Test, a property based test always has three parts:
- * A check operator
- * This tells ZIO Test that we are performing a property based test
- * One of more Gen values
- * You can think of each Gen as representing a distribution of potential values and each time we run a property based test we sample values from that distribution.
- * Generators As Streams Of Samples
- ```
- final case class Gen[-R, +A](
- sample: ZStream[R, Nothing, Sample[R, A]]
- )
-
- final case class Sample[-R, +A](
- value: A,
- shrinks: ZStream[R, Nothing, Sample[R, A]]
- )
- ```
- * For example, we could imagine a generator that generates values by opening a local file with test data, reading the contents of that file into memory, and each time generating a value based on one of the lines in that file.
- * assertion
-* https://zio.dev/api/zio/test/magnolia/index.html
- * traitDeriveGen[A] extends AnyRef
- A DeriveGen[A] can derive a generator of A values.
-* To create generators for a data type we will generally follow a two step process.
- * First, construct generators for each part of the data type.
- * Second, combine these generators using operators on Gen such as flatMap, map,
- and oneOf to build a generator for your data type out of these simpler generators.
- ```
- final case class Stock(ticker: String, price: Double, currency: Currency)
-
- lazy val genStock: Gen[Any, Stock] = for {
- ticker <- genTicker
- price <- genPrice
- currency <- genCurrency
- } yield Stock(ticker, price, currency)
- ```
- * One potential inefficiency you may have noticed in some of the examples above is that the flatMap operator requires us to run our generators sequentially, because the second generator we use can depend on the value generated by the first generator
- * ZIO Test supports this through the zipWith and zip operators and their symbolic alias <&>
- * These will generate the two values in parallel and then combine them into a tuple or using the specified function.
-* This illustrates a helpful principle for working with generators, which is to prefer transforming generators instead of filtering generators.
- ```
- val ints: Gen[Random, Int] = Gen.int(1, 100)
- val evens: Gen[Random, Int] = ints.map(n => if (n % 2 == 0) n else n + 1)
- ```
- * We will see below that we can also filter the values produced by generators, but this has a cost because we have to “throw away” all of the generated data that
- doesn’t satisfy our predicate
-* The either operator is helpful for when we want to generate data for sum types that can be one type or another, such as the Currency data type above.
- ```
- def genTry[R <: Random, A](gen: Gen[R, A]): Gen[R, Try[A]] = Gen.either(Gen.throwable, gen).map {
- case Left(e) => Failure(e)
- case Right(a) => Success(a) }
- ```
- * The first is the oneOf operator, which picks from one of the specified generators with equal probability
- * The second is the elements operator, which is like oneOf but just samples from one of a collection of concrete values instead of from one of a collection of generators
+* is an approach where the framework generates test cases
+* advantage: allows to quickly test a large number of test cases
+ * potentially: reveal not obvious counterexamples
+* typically generate ~ 100-200 test cases
+ * Int ~2 billion values
+ * complex data types => number of possibilities increases exponentially
+ * complement property based testing with traditional tests (for particular degenerate cases)
+* common mistake: generator is not general enough
+ * example: generating user input using ASCII
+ * what about: 普通话 ?
+* generator represents a distribution of potential values
+ * each time we run a property based test we sample values from that distribution
  ```
- sealed trait Currency
- case object USD extends Currency
- case object EUR extends Currency case object JPY extends Currency
+ final case class Gen[-R, +A](
+  sample: ZStream[R, Nothing, Sample[R, A]]
+ )
 
- val genCurrency: Gen[Random, Currency] = Gen.elements(JPY, USD, EUR)
+ final case class Sample[-R, +A](
+ value: A,
+ shrinks: ZStream[R, Nothing, Sample[R, A]]
+ )
+ ```
+* create generators
+ * construct generators for each field
+ * combine with operators
+ * example: flatMap, map, oneOf, zip
+ * example
+ ```
+ val genAccount2: Gen[Any, Account] =
+ (Gen.uuid <*> // symbolic alias for zip and zipWith; generate values in parallel
+ Gen.fromIterable(AccountStatus.values) <*>
+ Gen.string1(Gen.char)
+ ).map { case (uuid, status, str) => Account(AccountId(uuid), status, NonEmptyString.unsafeFrom(str))
+ }
+ ```
+* auto-deriving generator
+ * example
+ ```
+ val genAccount: Gen[Any, Account] = DeriveGen[Account] // implicit for each field
+ ```
+ * lib: https://zio.dev/api/zio/test/magnolia/index.html
+* don't use filter - transform instead
+ * filtering = "throw away" data that doesn’t satisfy our predicate
+ * example
+ ```
+ val evens: Gen[Random, Int] = ints.map(n => if (n % 2 == 0) n else n + 1) // transformation
  ```
-* For example, if we wanted to generate a pair of integers we could do it like this:
- val pairs: Gen[Random, (Int, Int)] = Gen.int <*> Gen.int
-* Random And Deterministic Generators
- * Traditionally in property based testing there has been a distinction between random and deterministic property based testing.
- * In random property based testing, values are generated using a pseudorandom number generator based on some initial seed.
- * The disadvantage of property based testing is that it is impossible for us to ever prove a property with random property based testing, we can merely fail to falsify it.
-* Samples And Shrinking
- * Typically when we run property based tests the values will be generated randomly and so when we find a counterexample to a property it will typically not be the
- “simplest” counterexample.
- * To help us it is useful if the test framework tries to shrink failures to ones that are “simpler” in some sense and still violate the property.
- * First, we want to generate values that are “smaller” than the original value in some sense. This could mean closer to zero in terms of numbers or closer to zero size in terms of collections.
- * Instead of doing this ZIO Test uses a technique called integrated shrinking where every generator already knows how to shrink itself and all operators on generators also appropriately combine the shrinking logic of the original generators.
- * So a generator of even integers can’t possibly shrink to anything other than an even integer because it is built that way.
- * In addition to a value a Sample also contains a “tree” of possible “shrinkings” of that value. It may not be obvious from the signature but ZStream[R, Nothing, Sample[A]] represents a tree.
- * The root of the tree is the original value.
- * The next level of the tree consists of all the values for the samples in the shrink collection.
- * Each of these values in turn may have its own children, represented by its own shrink tree.
- * The shrink tree must obey the following invariants.
- * First, within any given level, values to the “left”, that is earlier in the stream, must be “smaller” than values that are later in the stream.
- * Second, all children of a value in the tree must be “smaller” than their parents.
- * We begin by generating the first Sample in the shrink stream and testing whether its value is also a counterexample to the property being tested.
- * If it is a valid counterexample, we recurse on that sample. If it is not, we repeat the process with the next Sample in the original shrink stream.
- * For example, the default shrinking logic for integral values first tries to shrink to zero, then to half the distance between the value and zero, then to half that distance, and so on. At each level we repeat the same logic.
- * Sample itself has its own operators such as map and flatMap for combining Sample values.
- * The map/flatMap operator conceptually transforms both the value of the sample as well as all of its potential shrinkings with the specified function
- * example
- * map to transform a generator to generate only even integers we are guaranteed that the shrinkings will also contain only even integers.
+* shrinking
+ * counterexample will typically not be the "simplest"
+ * test framework tries to shrink failures to ones that
+ * are "simpler" (in some sense)
+ * example: smaller integers, smaller collections
+ * and still violate the property
+ * ZIO Test uses "integrated shrinking"
+ * every generator already knows how to shrink itself
+ * all operators keep this property
+ * example: generator of even integers can’t shrink to 1
+ * under the hood
+ * Sample contains a "tree" of possible "shrinkings" for the value
+ * root: original value
+ * invariants
+ * any given level: value earlier in the stream, must be "smaller" than later values
+ * all children must be "smaller" than their parents
+ * machinery
+ 1. generate the first Sample in the shrink stream
+ 1. test whether its value is also a counterexample to the property being tested
+ * counterexample => recurse on that sample
+ * not => repeat with the next Sample in shrink stream
+ * example: shrinking logic for int
+ * first tries to shrink to zero
+ * then to half the distance between counterexample and zero
+ * then to half that distance, and so on
 
 ## seed
 * TestRandom service provides a testable implementation of the Random service.