Merge pull request #27 from cucumber/documentation

Add more documentation on Scala specificities

Author: gaeljw

README.md

@@ -1,29 +1,13 @@
-# cucumber-jvm-scala
-[![Maven Central](https://img.shields.io/maven-central/v/io.cucumber/cucumber-scala_2.12.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22io.cucumber%22%20AND%20a:%22cucumber-scala_2.12%22)
-[![Build Status](https://travis-ci.org/cucumber/cucumber-jvm-scala.svg?branch=master)](https://travis-ci.org/cucumber/cucumber-jvm-scala)
-
-
-## Dependency
+# Cucumber Scala
 
-### SBT
-To use cucumber-jvm-scala in your project, add the following line to your `build.sbt`
-
-```scala
-libraryDependencies += "io.cucumber" %% "cucumber-scala" % "4.7.1" % Test
-```
+[![Maven Central](https://img.shields.io/maven-central/v/io.cucumber/cucumber-scala_2.13.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22io.cucumber%22%20AND%20a:%22cucumber-scala_2.13%22)
+[![Build Status](https://travis-ci.org/cucumber/cucumber-jvm-scala.svg?branch=master)](https://travis-ci.org/cucumber/cucumber-jvm-scala)
 
-### Maven
-To use cucumber-jvm-scala in your project, add the following dependency to your `pom.xml`:
+Cucumber Scala is the Scala implementation of [Cucumber](https://cucumber.io/).
 
+## Help & Support
 
-```xml
-<dependency>
-    <groupId>io.cucumber</groupId>
-    <artifactId>cucumber-scala_2.12</artifactId>
-    <version>4.7.1</version>
-    <scope>test</scope>
-</dependency>
-```
+See: https://cucumber.io/support
 
 ## Compatibility matrix
 
@@ -35,33 +19,25 @@ which can be different.
 | 5.6.0                  | 5.6.0            | 2.11, 2.12, 2.13 |
 | 4.7.1                  | 4.7.1            | 2.11, 2.12, 2.13 |
 
-## Migrating from 4.x to 5.x
-
-If you are using Cucumber Scala 4.7.x and want to upgrade to 5.x, please note there are some major changes in addition to the Cucumber upgrade itself.
-
-### Packages
-
-All Cucumber Scala classes are now under `io.cucumber.scala` package instead of `cucumber.api.scala`.
-
-### Before/BeforeStep/After/AfterStep definitions
-
-The `Before`, `BeforeStep`, `After` and `AfterStep` definitions have slightly changed:
-- to apply only with some tags, the variable list of tags as `String*` is replaced by a single tag expression of type `String`.
-- if providing both an order and a tag expression, the order is now the second parameter instead of the first.
-This is more consistent with the Java implementation.
+## Getting started
 
-For instance, the following code:
+- [Installation](./docs/install.md)
+- Upgrade notes
+  - [Version 5.x](docs/upgrade_v5.md)
+- Documentation
+  - [Basic usage](docs/usage.md)
+  - [Step Definitions](docs/step_definitions.md)
+  - [Hooks](docs/hooks.md)
+- [Example project](examples/README.md)
+- [Reference documentation for Java](https://docs.cucumber.io/docs/cucumber/)
+- [Changelog](https://github.com/cucumber/cucumber-jvm-scala/releases)
 
-```scala
-Before(1, "@tag1", "@tag2") { _ =>
-  // Do Something    
-}
-```
+## Contributing
 
-Is replaced by:
+Any contribution is welcome:
+- completing or fixing documentation
+- reporting or fixing issue
+- reporting missing feature (compared to other implementations)
+- developing a new feature
 
-```scala
-Before("@tag1 or @tag2", 1) { _ =>
-  // Do Something    
-}
-```
+Please use this Github project for contributing, either through an issue or a Pull Request.

docs/hooks.md

@@ -0,0 +1,85 @@
+# Hooks
+
+Hooks are blocks of code that can run at various points in the Cucumber execution cycle.
+They are typically used for setup and teardown of the environment before and after each scenario.
+
+See the [reference documentation](https://docs.cucumber.io/docs/cucumber/api/#hooks).
+
+## Scenario hooks
+
+Scenario hooks run for every scenario.
+
+### Before
+
+`Before` hooks run before the first step of each scenario.
+
+```scala
+Before { scenario : Scenario =>
+  // Do something before each scenario
+}
+```
+
+### After
+
+`After` hooks run after the last step of each scenario.
+
+```scala
+After { scenario : Scenario =>
+  // Do something after each scenario
+}
+```
+
+## Step hooks
+
+Step hooks invoked before and after a step.
+
+### BeforeStep
+
+```scala
+BeforeStep { scenario : Scenario =>
+  // Do something before step
+}
+```
+
+### AfterStep
+
+```scala
+AfterStep { scenario : Scenario =>
+  // Do something after step
+}
+```
+
+## Conditional hooks
+
+Hooks can be conditionally selected for execution based on the tags of the scenario.
+
+```scala
+Before("@browser and not @headless") { _ =>
+  // Do something before each scenario with tag @browser but not @headless
+}
+```
+
+## Order
+
+You can define an order between multiple hooks.
+
+```scala
+Before(10) { _ =>
+  // Do something before each scenario
+}
+
+Before(20) { _ =>
+  // Do something before each scenario
+}
+```
+
+The **default order is 1000**.
+
+## Conditional and order
+
+You mix up conditional and order hooks with following syntax:
+```scala
+Before("@browser and not @headless", 10) { _ =>
+  // Do something before each scenario
+}
+```

docs/install.md

@@ -0,0 +1,24 @@
+# Installation
+
+## Dependency
+
+### SBT
+
+To use Cucumber Scala in your project, add the following line to your `build.sbt`:
+
+```scala
+libraryDependencies += "io.cucumber" %% "cucumber-scala" % "4.7.1" % Test
+```
+
+### Maven
+
+To use Cucumber Scala in your project, add the following dependency to your `pom.xml`:
+
+```xml
+<dependency>
+    <groupId>io.cucumber</groupId>
+    <artifactId>cucumber-scala_2.12</artifactId>
+    <version>4.7.1</version>
+    <scope>test</scope>
+</dependency>
+```

docs/step_definitions.md

@@ -0,0 +1,40 @@
+# Step definitions
+
+Step definitions (`Given`, `When`, `Then`) are the glue between features written in Gherkin and the actual tests implementation.
+
+Cucumber supports two types of expressions:
+
+- Cucumber expressions
+- Regular expressions
+
+See also the [reference documentation](https://docs.cucumber.io/docs/cucumber/step-definitions/#expressions).
+
+## Cucumber expressions
+
+[Cucumber expressions](https://docs.cucumber.io/docs/cucumber/cucumber-expressions/)
+
+The following Gherkin step:
+```gherkin
+Given I have 42 cucumbers in my belly
+```
+
+Can be implemented with following Cucumber Expression in Scala:
+```scala
+Given("""I have {int} cucumbers in my belly"""){ (cucumberCount: Int) =>
+  // Do something    
+}
+```
+
+## Regular expressions
+
+The following Gherkin step:
+```gherkin
+Given I have 42 cucumbers in my belly
+```
+
+Can be implemented with following Regular Expression in Scala:
+```scala
+Given("""^I have (\d+) cucumbers in my belly$"""){ (cucumberCount: Int) =>
+  // Do something    
+}
+```

docs/upgrade_v5.md

@@ -0,0 +1,36 @@
+# Upgrading from 4.x to 5.x
+
+If you are using Cucumber Scala 4.7.x and want to upgrade to 5.x, please note there are some major changes in addition to the Cucumber upgrade itself.
+
+Starting from version 5.x, Cucumber Scala will try to be as close as possible to the Cucumber Java implementation while remaining Scala oriented.
+This means that package names, parameters order, internal code... will be more consistent with the Java implementation.
+
+## Packages
+
+All Cucumber Scala classes are now under `io.cucumber.scala` package instead of `cucumber.api.scala`.
+
+## Hooks
+
+The `Before`, `BeforeStep`, `After` and `AfterStep` definitions have slightly changed:
+- to apply only to scenarios with some tags, the `String*` parameter is replaced by a single tag expression of type `String`.
+This changes comes from Cucumber itself.
+- if providing both an order and a tag expression, the order is now the second parameter instead of the first.
+This is more consistent with the Java implementation.
+
+For instance, the following code:
+
+```scala
+Before(1, "@tag1", "@tag2") { _ =>
+  // Do Something    
+}
+```
+
+Is replaced by:
+
+```scala
+Before("@tag1 or @tag2", 1) { _ =>
+  // Do Something    
+}
+```
+
+See also the [Hooks documentation](hooks.md).

docs/usage.md

@@ -0,0 +1,70 @@
+# Basic Usage
+
+## Glue code
+
+To use Cucumber Scala, all your glue code (steps or hooks) has to be defined in **classes** extending both the `ScalaDsl` trait and a language trait.
+
+For instance, to use the English flavour:
+```scala
+import io.cucumber.scala.{EN, ScalaDsl}
+
+class MyGlueClass extends ScalaDsl with EN {
+
+  // Here some steps or hooks definitions
+
+  Given("""I have {int} cucumbers in my belly"""){ (cucumberCount: Int) =>
+    // Do something    
+  }
+
+}
+```
+
+Cucumber will automatically load all the glue code defined in classes available in the "glue path" (more details in the Run documentation) inheriting `ScalaDsl`.
+
+### Using traits
+
+You can define glue code in **traits** as well and have a **class** extending the traits you need.
+
+For instance, you can do things like this:
+```scala
+import io.cucumber.scala.{EN, ScalaDsl}
+
+trait StepsForThis extends ScalaDsl with EN {
+  // Glue code
+}
+
+trait StepsForThat extends ScalaDsl with EN {
+  // Glue code
+}
+
+class MyStepDefinitions extends StepsForThis with StepsForThat {
+}
+```
+
+**Note:** using traits can help you split your tests in different groups and provide some steps only to some tests.
+
+### Using objects
+
+You can also define glue code in **objects**.
+
+It's **not recommended** though, because by definition objects are singleton and if your glue code is stateful you will probably have "state conflicts" between your scenarios.
+
+## Running Cucumber tests
+
+See also the Running Cucumber for Java [documentation](https://docs.cucumber.io/docs/cucumber/api/#running-cucumber).
+
+Add the `cucumber-junit` dependency to your project.
+
+Then create a runner class like this:
+```scala
+import io.cucumber.junit.{Cucumber, CucumberOptions}
+import org.junit.runner.RunWith
+
+@RunWith(classOf[Cucumber])
+@CucumberOptions()
+class RunCucumberTest
+```
+
+You can define several options like:
+- the "glue path" (default to current package): packages in which to look for glue code
+- the "features path" (default to current folder): folder in which to look for features file

examples/README.md

@@ -0,0 +1,3 @@
+# Cucumber Scala Example
+
+This project is an example of Cucumber Scala integration in a Scala Maven project.