Skip to content

Feature/tut docs #75

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 11 commits into from
Nov 26, 2018
Merged

Feature/tut docs #75

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
e267353
Adding tut plugin
alexflav23 Nov 25, 2018
574e677
Add in readme for the project
alexflav23 Nov 25, 2018
e54ed87
Updating the documentation to use tut
alexflav23 Nov 25, 2018
5ee79d8
Adding examples of how to derive new types.
alexflav23 Nov 25, 2018
d122d41
Simplifying the logic with env variables
alexflav23 Nov 25, 2018
e0ae34d
Removing assertions test as assertions have been removed.
alexflav23 Nov 25, 2018
e044acd
Updating patience configuration
alexflav23 Nov 25, 2018
a7c8b1d
Adding environment exports
alexflav23 Nov 26, 2018
028d7f0
Trying to fix Travis logic
alexflav23 Nov 26, 2018
2f6a41b
Adding docs folder output
alexflav23 Nov 26, 2018
e45ab62
Changing entrypoint into readme
alexflav23 Nov 26, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion .travis.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,14 @@ branches:
- develop
matrix:
include:
- scala: 2.12.6
- scala: 2.12.7
jdk: oraclejdk8
env: RUN_WITH_COVERAGE=true PUBLISH_ARTIFACT=true

env:
global:
- RUN_WITH_COVERAGE: false
- PUBLISH_ARTIFACT: false
- GH_REF: github.com/outworkers/util.git
- secure: Onl6jQhDgCHVhsxIhC2FltwTlvTWI5815lI9wsb79OvE+Xl/hh8XcafOBzUJ/LtKmt021oieOsR53RAdIJDKhNrKo3AQYoyp3rAX48zCInE0Y29slKVCwj51w5Mns+aYlPbJcHJvRNWkFIpaQ1AmBvkHfc0A0rxfoSB1lOIrtHs=
- secure: k/DGy5KkvzmQNJEfazsEoD6biwkIoYC9DyjhDTMCxhXLz/mURsCtfhdWo3Uz4nhuX3qDK0N/6C6BTwl0ktVEA7eH8XZQY/dW1lLTY3jglD2U/FhAfCngbcI+ToL5kdK77Zy4LKvu4XBKXfSusI20E1gbK+Tjp1uCkNvVaAyyVv0=
Expand Down
335 changes: 2 additions & 333 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,341 +7,10 @@ latest version of `util` available. The badges are automatically updated when a

![Util](https://s3-eu-west-1.amazonaws.com/websudos/oss/logos/util.png "Outworkers Util")

### Table of contents ###
### Documentation

<ol>
<li><a href="#integrating-the-util-library">Integrating the util library</a></li>

<li>
<p><a href="#util-parsers">util-parsers</a></p>
<ul>
<li><a href="#option-parsers">Option parsers</a></li>
<li><a href="#applicative-parsers">Applicative parsers</a></li>
</ul>
</li>

<li>
<p><a href="#util-parsers">util-parsers-cats</a></p>
<ul>
<li><a href="#option-parsers">Option parsers</a></li>
<li><a href="#applicative-parsers">Applicative parsers</a></li>
</ul>
</li>

<li>
<p><a href="#util-testing">util-testing</a></p>
<ul>
<li><a href="#async-assertions">Async assertions</a></li>
<li><a href="#data-sampling">Data sampling</a></li>
<li><a href="#automated-sampling">Automated sampling</a></li>
</ul>
</li>
The official documentation is found [here](./docs/README.md)

<li>
<p><a href="#util-zookeeper">util-zookeeper</a></p>
<ul>
<li><a href="#zookeeperinstance">ZooKeeperInstance</a></li>
<li><a href="#zookeeperconf>ZooKeeperConf</a></li>
</ul>
</li>

<li><a href="#contributors">Copyright</a></li>
<li><a href="#style-guidelines">Scala Style Guidelines</a></li>
<li><a href="#git-flow">Git Flow</a></li>
<li><a href="#contributing">Contributing</a></li>
<li><a href="#copyright">Copyright</a></li>
</ol>


### Integrating the util library ###
<a href="#table-of-contents">Back to top</a>


The util library is designed to wrap common functionality in all our frameworks and offer it at the convenience of a dependency. Anything that will be useful
long term to a great number of people belongs in these modules, to avoid duplication and help make our devs aware they can simply use what already exists.

The full list of available modules is:

```scala

libraryDependencies ++= Seq(
"com.outworkers" %% "util-lift" % Versions.util,
"com.outworkers" %% "util-domain" % Versions.util,
"com.outworkers" %% "util-parsers" % Versions.util,
"com.outworkers" %% "util-parsers-cats" % Versions.util,
"com.outworkers" %% "util-validators" % Versions.util,
"com.outworkers" %% "util-validators-cats" % Versions.util,
"com.outworkers" %% "util-play" % Versions.util,
"com.outworkers" %% "util-urls" % Versions.util,
"com.outworkers" %% "util-testing" % Versions.util
)
```


### util-testing ###
<a href="#table-of-contents">Back to top</a>

The testing module features the ```AsyncAssertionsHelper```, which builds on top of ScalaTest to offer simple asynchronous assertions. We use this pattern
heavily throughout the Outworkers ecosystem of projects, from internal to DSL modules and so forth. Asynchronous testing generally offers a considerable
performance gain in code.


### Async assertions ###
<a href="#table-of-contents">Back to top</a>


The async assertions module features a dual API, so you can call the same methods on both ```scala.concurrent.Future``` and ```com.twitter.util.Future```.
The underlying mechanism will create an async ```Waiter```, that will wait for the future to complete within the given ```PatienceConfiguration```. The
awaiting is done asynchronously and the assertions are invoked and evaluated once the future in question has returned a result.

```scala
import com.outworkers.util.testing._

class MyTests extends FlatSuite with Matchers {

"The async computation" should "return 0 on completion" in {
val f: Future[Int] = .. // Pretend this is a Future just like any other future.
f.successful {
res => {
res shouldEqual 0
}
}
}

"This async computation" should "fail by design" in {
val f: Future[Unit] = ..

// You don't even need to do anything more than failure at this stage.
// If the Future fails, the test will succeed, as this method is used when you "expect a failure".
// You can however perform assertions on the error returned.
f.failing {
err => {
}
}
}

"This async computation" should "fail with a specific error" in {
val f: Future[Unit] = ..
f.failingWith[NumberFormatException] {
err => {
}
}
}

}
```


You can directly customise the ```timeout``` of all ```Waiters``` using the ScalaTest specific time span implementations and interval configurations.


```scala
import org.scalatest.concurrent.PatienceConfiguration
import org.scalatest.time.SpanSugar._

implicit val timeout: PatienceConfiguration.Timeout = timeout(20 seconds)

```

Summary:

- The dependency you need is ```"com.outworkers" %% "util-testing" % UtilVersion```.
- You have to import ```com.outworkers.util.testing._```.
- You have three main assertion methods, ```successful```, ```failing```, and ```failingWith```.
- You can configure the timeout of waiters with ```implicit val timeout: PatienceConfiguration.Timeout = timeout(20 seconds)```.
- The default timeout value is ```1 second```.


### Data sampling ###
<a href="#table-of-contents">Back to top</a>

This is a very common pattern we use in our testing and it's very easy to interchange this generation with something like ScalaCheck. The idea is very simple, you use type classes to define ways to sample a given type.
After you define such a one-time sampling type class instance, you have access to several methods that will allow you to generate test data.

It's useful to define such typeclass instances inside package objects, as they will be "invisibly" imported in to the scope you need them to. This is often really neat, albeit potentially confusing for novice Scala users.


```scala

import com.outworkers.util.testing._

@sample case class MyAwesomeClass(name: String, age: Int, email: String)
```

You may notice this pattern is already available in better libraries such as ScalaMock and we are not trying to provide an alternative to ScalaMock or compete with it in any way. Our typeclass generator approach only becomes very useful where you really care about very specific properties of the data.
For instance, you may want to get a user with a valid email address, or you may use the underlying factories to get a name that reassembles the name of a real person, and so on.

It's also useful when you want to define specific ways in which hierarchies of classes are composed together into a sample. If generation for the sake of generation is all you care about, then ScalaMock is probably more robust.


### Automated sampling

<a href="#table-of-contents">Back to top</a>

One interesting thing that happens when using the `@sample` annotation is that using `gen` immediately after it will basically
give you an instance of your `case class` with the fields appropiately pre-filled, and some of the basic scenarios are also name aware.

What this means is that we try to make the data feel "real" with respect to what it should be. Let's take the below example:

```scala
@sample case class User(
id: UUID,
firstName: String,
lastName: String,
email: String
)
```
This is interesting and common enough. What's more interesting is the output of `gen`.

```scala

val user = gen[User]

Console.println(user.trace())

/**
User(
id = 6be8914c-4274-40ee-83f5-334131246fd8
firstName = Lindsey
lastName = Craft
email = [email protected]
)
*/

```

So as you can see, the fields have been appropriately pre-filled. The email is a valid email, and the first and last name look like first and last names. For
anything that's in the default generation domain, including dates and country codes and much more, we have the ability to produce automated
appropriate values.

During the macro expansion phase, we check the annotation targets and try to infer the "natural" value based on the field name and type. So
if your field name is either "email" or "emailAddress" or anything similar enough, you will get an "email" back.


### Generating data

There are multiple methods available, allowing you to generate more than just the type:

- ```gen[T]```, used to generate a single instance of T.
- ```gen[X, Y]```, used to generate a tuple based on two samples.
- ```genOpt[T]```, convenience method that will give you back a ```Some[T](..)```.
- ```genList[T](limit)```, convenience method that will give you back a ```List[T]```. The numbers of items in the list is equal to the ```limit``` and has a default value of 5 if not specified.
- ```genMap[T]()```, convenience method that will give you back a ```Map[String, T]```.


There is also a default list of available generators for some default types, and to get to their value simply use the `value` method if the type is not a primitive. For things like ```EmailAddress```, the point of the extra class is obviously to distinguish the type during implicit resolution, but you don't need to use our abstraction at all, there will always be an easy way to get to the underlying generated primitives.

In the case of email addresses, you can use ```gen[EmailAddress].value```, which will correctly generate a valid ```EmailAddress``` but you can work directly with a ```String```.

- ```scala.Int```
- ```scala.Double```
- ```scala.Float```
- ```scala.Long```
- ```scala.String```
- ```scala.math.BigDecimal```
- ```scala.math.BigInt```
- ```java.util.Date```
- ```java.util.UUID```
- ```org.joda.time.DateTime```
- ```org.joda.time.LocalDate```
- ```com.outworkers.util.domain.Definitions.EmailAddress(value)```
- ```com.outworkers.util.domain.Definitions.FirstName(value)```
- ```com.outworkers.util.domain.Definitions.LastName(value)```
- ```com.outworkers.util.domain.Definitions.FullName(value)```
- ```com.outworkers.util.domain.Definitions.CountryCode(value)```
- ```com.outworkers.util.domain.Definitions.Country(value)```
- ```com.outworkers.util.domain.Definitions.City(value)```
- ```com.outworkers.util.domain.Definitions.ProgrammingLanguage(value)```
- ```com.outworkers.util.domain.Definitions.LoremIpsum(value)```


### util-parsers ###
<a href="#table-of-contents">Back to top</a>

The parser module features an easy to use and integrate set of ScalaZ Applicative based parsers, with an ```Option``` based parser variant. It allows us to
seamlessly deal with validation chains at REST API level or whenever validation is involved. Whether it's monadic composition of options or chaining of
applicative functors to obtain a "correct" chain, the parser module is designed to offer an all-you-can-eat buffet of mini parsers that can be easily
composed to suit any validation needs.

Each parser comes in three distinct flavours, a ```ValidationNel``` parser that parsers the end type from a ```String``` and returns the type itself,
a parser that parses an end result from an ```Option[String]``` and parserOpt variant that returns an ```Option[T]``` instead of a ```ValidationNel[String,
T]```, which allows for Monadic composition, where you need to "short-circuit" evaluation and validation, instead of computing the full chain by chaining
applicatives.

### Option parsers ###
<a href="#table-of-contents">Back to top</a>

The full list of optional parsers is:

| Type | Input type | Parser Output type |
| --------------- |---------------------------| --------------------------------- |
| Int | String\|Option[String] | ValidationNel[String, Int] |
| Long | String\|Option[String] | ValidationNel[String, Long] |
| Double | String\|Option[String] | ValidationNel[String, Double] |
| Float | String\|Option[String] | ValidationNel[String, Float] |
| UUID | String\|Option[String] | ValidationNel[String, UUID] |
| Email | String\|Option[String] | ValidationNel[String, String] |
| DateTime | String\|Option[String] | ValidationNel[String, org.joda.time.DateTime] |

Option parsers are designed for chains where you want to short-circuit and exit to result as soon a parser fails. This short-circuit behaviour is the default
```flatMap``` behaviour of an ```Option```, as soon as an ```Option``` is ```None``` the chain breaks. Unlike applicatives,
the evaluation sequence of options will be escaped and you cannot for instance return an error for every parser that couldn't validate. Instead,
you will only get the first error in the sequence.

An example of how to use ```Option``` parsers might be:

```scala

import com.outworkers.util.parsers._

object Test {
def optionalParsing(email: String, age: String): Unit = {
for {
validEmail <- parseOpt[EmailAddress](email)
validAge <- parseOpt[Int](age)
} yield s"This person can be reached at $validEmail and is $validAge years old"
}
}

```


### Applicative parsers ###
<a href="#table-of-contents">Back to top</a>

The full list of ScalaZ Validation based applicative parsers is:

| Type | Input type | Parser Output type |
| --------------- |---------------------------| --------------------------------- |
| Int | String\|Option[String] | ValidationNel[String, Int] |
| Long | String\|Option[String] | ValidationNel[String, Long] |
| Double | String\|Option[String] | ValidationNel[String, Double] |
| Float | String\|Option[String] | ValidationNel[String, Float] |
| UUID | String\|Option[String] | ValidationNel[String, UUID] |
| Email | String\|Option[String] | ValidationNel[String, String] |
| DateTime | String\|Option[String] | ValidationNel[String, org.joda.time.DateTime] |

To illustrate the basic usage of applicative parsers and how to chain them, have a look below.

```scala

import scalaz._
import scalaz.Scalaz._
import com.outworkers.util.parsers._

object Test {

def registerUser(str: String, age: String): Unit = {
(parse[EmailAddress](str) |@| parse[Int](age)) {
(validEmail, validAge) => {
}
}.fold {
// ..
}
}

}
```

### Contributors
<a href="#table-of-contents">Back to top</a>
Expand Down
26 changes: 25 additions & 1 deletion build.sbt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -179,7 +179,8 @@ lazy val baseProjectList: Seq[ProjectReference] = Seq(
testing,
testingTwitter,
macros,
tags
tags,
readme
)

lazy val util = (project in file("."))
Expand Down Expand Up @@ -414,3 +415,26 @@ lazy val validators = (project in file("util-validators"))
parsers,
testing % Test
)

lazy val readme = (project in file("readme"))
.settings(sharedSettings: _*)
.dependsOn(
domain,
lift,
liftCats,
parsers,
parsersCats,
validatorsCats,
validators,
samplers,
testing,
testingTwitter,
macros,
tags
).settings(
tutSourceDirectory := sourceDirectory.value / "main" / "tut",
tutTargetDirectory := util.base / "docs",
libraryDependencies ++= Seq(
"org.scalatest" %% "scalatest" % Versions.scalatest % "tut"
)
).enablePlugins(TutPlugin)
Loading