Docusaurus website

Adds a docusaurus website, and the required logic to publish it to gh-pages upon release. 

Fixes ISSUE-42

.drone.yml

@@ -4,11 +4,30 @@ name: default
 steps:
 
   # Compile the code/run tests
-- name: build
-  image: hseeberger/scala-sbt:8u242_1.3.8_2.12.10
+# - name: build
+#   image: hseeberger/scala-sbt:8u242_1.3.8_2.12.10
+#   commands:
+#   - sbt ci
+#   - echo Built $(cat version)
+#   environment:
+#     COURSIER_CACHE: .cache/coursier
+#   volumes:
+#     - name: sbt-cache
+#       path: /root/.sbt
+
+- name: build docker image
+  image: docker
+  volumes:
+  - name: dockersock
+    path: /var/run/docker.sock
+  commands:
+  - docker build -t weaver-scala-sbt-yarn:latest docker/
+
+- name: build-site
+  image: weaver-scala-sbt-yarn:latest
+  pull: if-not-exists
   commands:
-  - sbt ci
-  - echo Built $(cat version)
+  - sbt 'docs/docusaurusCreateSite'
   environment:
     COURSIER_CACHE: .cache/coursier
   volumes:
@@ -35,9 +54,31 @@ steps:
   - name: sbt-cache
     path: /root/.sbt
 
+- name: publish-site
+  image: weaver-scala-sbt-yarn:latest
+  pull: if-not-exists
+  commands:
+  - mkdir -p $HOME/.ssh
+  - ssh-keyscan -t rsa github.bamtech.co >> $HOME/.ssh/known_hosts
+  - sbt 'docs/docusaurusPublishGhpages'
+  environment:
+    COURSIER_CACHE: .cache/coursier
+    GIT_USER: $DRONE_COMMIT_AUTHOR
+    GITHUB_DEPLOY_KEY:
+      from_secret: github_deploy_public_key
+  when:
+    ref:
+      - refs/tags/v*
+  volumes:
+    - name: sbt-cache
+      path: /root/.sbt
+
 volumes:
 - name: sbt-cache
   temp: {}
+- name: dockersock
+  host:
+    path: /var/run/docker.sock
 
 ---
 kind: secret
@@ -48,4 +89,3 @@ kind: secret
 name: password
 data: krBDYD3HhDKTls34m7vad5oLDsk7PkLgmx3u10B3nCIpbYwWc+mq
 
-

.gitattributes

@@ -0,0 +1,5 @@
+*.png filter=lfs diff=lfs merge=lfs -text
+*.svg filter=lfs diff=lfs merge=lfs -text
+*.gif filter=lfs diff=lfs merge=lfs -text
+*.psd filter=lfs diff=lfs merge=lfs -text
+*.webp filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -42,6 +42,14 @@ snapshots
 dynamodb_lib
 *.db
 
+# Node
+node_modules
+website/translated_docs
+website/build/
+website/yarn.lock
+website/node_modules
+website/i18n/*
+
 .bloop
 .vscode
 .metals

README.md

@@ -29,7 +29,7 @@ libraryDependencies +=  "com.disneystreaming.oss" %% "weaver-scalacheck" % "x.y.
 
 ## Motivation
 
-![time](docs/screenshots/time.png)
+![time](docs/assets/time.png)
 
 Weaver aims at providing a nice experience when writing and running tests :
 
@@ -112,7 +112,7 @@ The various `test` functions have in common that they expect the developer to re
 
 The most convenient way to build `Expectations` is to use the `expect` function. It captures the boolean expression at compile time and provides useful feedback on what goes wrong when it does :
 
-![Oops](docs/screenshots/oops.png)
+![Oops](docs/assets/oops.png)
 
 Nothing prevents the user from building their own expectations functions to resemble what they're used to.
 

build.sbt

@@ -4,8 +4,7 @@ import sbtcrossproject.CrossPlugin.autoImport.{ crossProject, CrossType }
 addCommandAlias("ci",
                 ";project root ;versionDump; scalafmtCheckAll ;+clean ;+test:compile ;+test")
 
-addCommandAlias("release",
-                ";project root ;+publish")
+addCommandAlias("release", ";project root ;+publish")
 
 lazy val root = project
   .in(file("."))
@@ -33,6 +32,20 @@ lazy val core = crossProject(JVMPlatform)
 lazy val coreJVM = core.jvm
 // lazy val coreJS  = core.js
 
+lazy val docs = project
+  .in(file("modules/docs"))
+  .enablePlugins(DocusaurusPlugin, MdocPlugin)
+  .settings(
+    moduleName := "docs",
+    watchSources += (ThisBuild / baseDirectory).value / "docs",
+    libraryDependencies ++= Seq(
+      "org.http4s" %% "http4s-dsl"          % "0.21.0",
+      "org.http4s" %% "http4s-blaze-server" % "0.21.0",
+      "org.http4s" %% "http4s-blaze-client" % "0.21.0"
+    )
+  )
+  .dependsOn(coreJVM)
+
 lazy val framework = crossProject(JVMPlatform)
   .crossType(CrossType.Pure)
   .in(file("modules/framework"))

docker/Dockerfile

@@ -0,0 +1,25 @@
+FROM hseeberger/scala-sbt:8u242_1.3.8_2.12.10
+
+####### YARN INSTALLATION ########
+
+## Found in https://github.com/yarnpkg/yarn/issues/6914#issuecomment-454165516
+
+# Setup the base OS
+RUN apt-get update -qq \
+ && apt-get install -y --no-install-recommends build-essential  \
+    apt-transport-https curl ca-certificates gnupg2 apt-utils nodejs
+
+# Install node from nodesource
+ RUN curl -sL https://deb.nodesource.com/setup_10.x | bash - \
+  && apt-get install -y nodejs
+
+# Install yarn
+RUN curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | apt-key add - \
+ && echo "deb https://dl.yarnpkg.com/debian/ stable main" | tee /etc/apt/sources.list.d/yarn.list \
+ && apt-get update -qq \
+ && apt-get install -y yarn
+
+# Test
+RUN yarn --version
+
+####### END OF YARN INSTALLATION ########

docs/common_usage.md

@@ -0,0 +1,33 @@
+---
+id: common_usage
+title: Common usage
+---
+
+Start with importing the following :
+
+```scala mdoc
+import weaver._
+```
+
+The most basic usage is to extend `SimpleIOSuite`. Tests are registered imperatively, very much like in scalatest's `FunSuite` or in `utest`, but
+
+```scala mdoc
+import cats.effect._
+
+// Suites must be "objects" for them to be picked by the framework
+object MySuite extends SimpleIOSuite {
+
+  val randomUUID = IO(java.util.UUID.randomUUID())
+
+  // A test for side-effecting functions
+  simpleTest("hello side-effects") {
+    for {
+      x <- randomUUID
+      y <- randomUUID
+    } yield expect(x != y)
+  }
+
+}
+```
+
+

docs/expectations.md

@@ -0,0 +1,40 @@
+---
+id: expectations
+title: Expectations (assertions)
+---
+
+Expectations are pure, composable values. This forces developers to separate the scenario of a test from the checks it performs, which generally makes for cleaner/clearer code.
+
+The easiest way to construct them is to call the `expect` macro, which is built using the [expecty](https://github.com/eed3si9n/expecty/) library.
+
+```scala mdoc
+import weaver._
+import cats.effect.IO
+
+object MySuite2 extends SimpleIOSuite {
+
+  pureTest("And/Or composition") {
+    expect(1 != 2) and expect(2 != 1) or expect(2 != 3)
+  }
+
+  pureTest("Foldable operations") {
+    val list = List(1,2,3)
+    import cats.instances.list._
+    forall(list)(i => expect(i > 0)) and
+    exists(list)(i => expect(i == 3))
+  }
+
+  pureTest("Non macro-based expectations") {
+    val condition : Boolean = false
+    if (condition) success else failure("Condition failed")
+  }
+
+  simpleTest("Failing fast expectations") {
+    for {
+      h <- IO.pure("hello")
+      _ <- expect(h.nonEmpty).failFast
+    } yield success
+  }
+
+}
+```

docs/installation.md

@@ -0,0 +1,42 @@
+---
+id: installation
+title: Installation
+---
+
+Weaver-test is currently published for **Scala 2.12 and 2.13**
+
+## SBT
+
+Refer yourself to the [releases](https://github.bamtech.co/OSS/weaver-test/releases) page to know the latest released version, and add the following (or scoped equivalent) to your `build.sbt` file.
+
+```scala
+resolvers += "dss oss" at "https://artifactory.us-east-1.bamgrid.net/artifactory/oss-maven"
+
+libraryDependencies += "com.disneystreaming.oss" %% "weaver-framework" % "x.y.z" % Test
+testFrameworks += new TestFramework("weaver.framework.TestFramework")
+
+// optionally (for ZIO usage)
+libraryDependencies +=  "com.disneystreaming.oss" %% "weaver-zio" % "x.y.z" % Test
+
+// optionally (for Scalacheck usage)
+libraryDependencies +=  "com.disneystreaming.oss" %% "weaver-scalacheck" % "x.y.z" % Test
+```
+
+## Mill
+
+```scala
+import mill._, scalalib._
+
+object foo extends ScalaModule {
+  def scalaVersion = "2.13.1"
+
+  object test extends Tests {
+    def ivyDeps = Agg(
+      ivy"com.disneystreaming.oss::weaver-framework:x.y.z",
+      ivy"com.disneystreaming.oss::weaver-scalacheck:x.y.z",
+      ivy"com.disneystreaming.oss::weaver-zio:x.y.z"
+    )
+    def testFrameworks = Seq("weaver.framework.TestFramework")
+  }
+}
+```

docs/logging.md

@@ -0,0 +1,36 @@
+---
+id: logging
+title: Logging information
+---
+
+Weaver allows provides with per-test lazy-loggers. The log statements are only ever reported if the test was unsuccessful. Because tests in weaver run in parallel by default, this makes it easier to tie printed information to the test they originated from.
+
+```scala mdoc
+import weaver._
+import cats.effect._
+
+object LoggedTests extends IOSuite {
+
+  // Only the logger is received as an argument
+  loggedTest("Just logging some stuff") { log =>
+    for {
+      _ <- log.info("oopsie daisy")
+    } yield expect(2 + 2 == 5)
+  }
+
+
+  // We can oviously have tests receive loggers AND shared resources
+  override type Res = String
+  override def sharedResource : Resource[IO, Res] =
+    Resource.pure[IO, Res]("hello")
+
+  // Both the logger and the resource are received as arguments
+  test("Good requests lead to good results") { (sharedString, log) =>
+    for {
+      _ <- log.info(sharedString)
+    } yield expect(2 + 2 == 4)
+  }
+
+}
+```
+

docs/motivation.md

@@ -0,0 +1,35 @@
+---
+id: motivation
+title: Motivation
+---
+
+## A test framework for integration tests
+
+Weaver was built for integration/end-to-end tests. It aims at making tests faster and make issues easier to debug, by treating effect types (IO/Task/ZIO) as first-class citizens.
+
+## History
+
+Weaver-test was born in 2018 as an experiment, trying to speedup an extremely slow, incredibly I/O heavy test suite that was implemented with scalatest, and was making numerous http calls to real services, verifying their deployments and orchestration.
+
+Neither **cats-effect** nor **fs2** had reached their respective 1.0.0 at the time, and **ZIO** was not yet known under that name.
+
+Nethertheless, built on bleeding edge libraries, and offering a principled api  that didn't completely shift from more classic frameworks such as utest, specs2, scalatest, etc, **weaver** allowed to tremendously speed up the test suite in question by parallelising its test, weaving their respective computations together in a single IO value that was executed by the framework.
+
+From there, additional problems were tackled, among which :
+
+* Making errors appear at the very end of the report, no matter how many suites wwere run.
+* Ensuring a principled sharing of resources across tests, using `cats.effect.Resource` to guarantee their release.
+* Providing a lazy logger to enrich reporting with ad-hoc information, ensuring
+it only gets displayed when a test fails.
+* Treating assertions as pure values that could be composed together, negated, discarded ...
+
+
+## Thank you note
+
+A **HUGE** thank you to Alexandru Nedelcu, author of [Monix](https://github.com/monix/monix) and contributor to
+cats-effect, as he wrote the [minitest](https://github.com/monix/minitest)
+framework which got this framework started.
+
+Another **HUGE** thank eu to Eugene Yokota, author of [Expecty](https://github.com/eed3si9n/expecty/).
+
+And an obious thank you to the maintainers of cats and fs2. We stand on the shoulders of giants.