USAGE.md

Usage

• Project Setup
• Writing Tests
• Running Tests

Project Setup

1. Choose dependencies and add to SBT.
   Module descriptions are here. Take what you need and delete the rest.

   val TestStateVer = "2.4.1"
   
   libraryDependencies ++= Seq(
     "com.github.japgolly.test-state" %%% "core"                % TestStateVer % Test,
     "com.github.japgolly.test-state" %%% "dom-zipper"          % TestStateVer % Test,
     "com.github.japgolly.test-state" %%  "dom-zipper-jsoup"    % TestStateVer % Test,
     "com.github.japgolly.test-state" %%  "dom-zipper-selenium" % TestStateVer % Test,
     "com.github.japgolly.test-state" %%% "dom-zipper-sizzle"   % TestStateVer % Test,
     "com.github.japgolly.test-state" %%% "ext-cats"            % TestStateVer % Test,
     "com.github.japgolly.test-state" %%% "ext-nyaya"           % TestStateVer % Test,
     "com.github.japgolly.test-state" %%% "ext-scalajs-react"   % TestStateVer % Test,
     "com.github.japgolly.test-state" %%  "ext-selenium"        % TestStateVer % Test,
   )

   
   Please note that if your sbt is setup to use scalajs-bundler, currently you still need to enable the older JsDependenciesPlugin for the js dependencies from above to be included in your final js file. For example:

     lazy val client = (project in file("client"))
        .enablePlugins(ScalaJSPlugin)
        .enablePlugins(ScalaJSBundlerPlugin)
        .enablePlugins(JSDependenciesPlugin) // Needed even if you're using scalajs-bundler
   
     // scalajs-bundler style external js dependencies
     Compile / npmDependencies ++= Seq(
       "react"     -> "17.0.2",
       "react-dom" -> "17.0.2",
     )
     ....

2. Create a configuration for your needs.
   Each module has a trait containing all of its public API. Mix them into your own object. Later you can add additional configuration such as settings, or typeclasses for your data types.

   package my.app.test
   
   object MyTestState
     extends teststate.Exports                    // Core. Most important piece.
        with teststate.domzipper.jsoup.Exports    // This already extends Core
        with teststate.domzipper.selenium.Exports // This already extends Core
        with teststate.domzipper.sizzle.Exports   // This already extends Core
        with teststate.ExtCats
        with teststate.ExtNyaya
        with teststate.ExtScalaJsReact
   {
     // Additional config here if desired.
   
     // Example: customise how BankAccounts are displayed in test output.
     implicit val displayBankAccount: Display[BankAccount] =
       Display(_.accountNo)
   }

Writing Tests

1. Choose your types. This nearly always involves creating a small class for your Observations.
2. Create a Dsl instance. Use your DSL to create actions, assertions and invariants.
3. Compose everything to create a Test.

Running Tests

1. On your Test, call .run to execute it.
   (Technically execution depends on the context as described in TYPES.md. E.g. if the context is a cats.effect.IO then nothing will have been executed yet and you're free to call .unsafePerformIO yourself.)

2. The result will be a Report[E] where E (the error type) is by default a String. You're free to inspect the results if desired but...

3. Most likely you will just want to call .assert(), which print results to the screen and throws an exception on failure.

   Like this:

This project also comes with example projects.
If the above is unclear, reading/running one of the example projects will help.