docs: Add JUnit5 examples for TestBench9

articles/testing/browser-based/running-test-on-multiple-browsers.asciidoc

@@ -2,4 +2,4 @@
 title: Running Tests on Multiple Browsers in a Grid
 section-nav: hidden
 ---
-This page has moved: <<../end-to-end/multiple-browsers#,Running Tests on Multiple Browsers in a Grid>>
+This page has moved: <<../end-to-end/multiple-browsers#,Running Tests on Multiple Browsers>>

articles/testing/end-to-end/advanced-concepts.adoc

@@ -141,5 +141,24 @@ public void verifyServerExecutionTime() throws Exception {
 }
 ----
 
+== Running tests in parallel
+
+TestBench supports parallel tests execution using its own test runner (JUnit 4) or native link:https://junit.org/junit5/docs/current/user-guide/#writing-tests-parallel-execution[JUnit 5 parallel execution].
+
+Up to 50 test methods are executed simultaneously by default. The limit can be set using the `com.vaadin.testbench.Parameters.testsInParallel` system property.
+
+When running tests in parallel, you need to ensure that the tests are independent and don't affect each other in any way.
+
+=== Extending ParallelTest (JUnit 4)
+
+Usually, you want to configure something for all your tests, so it makes sense to create a common superclass, for example `public abstract class AbstractIT extends ParallelTest`.
+
+If your tests don't work in parallel, set the `com.vaadin.testbench.Parameters.testsInParallel` to `1`.
+
+=== Using native JUnit 5 parallel execution
+
+To run tests in parallel, extend the TestBench utility class `BrowserTestBase` or manually annotate test classes with `@Execution(ExecutionMode.CONCURRENT)`.
+
+To disable parallel execution, annotate the test class with `@Execution(ExecutionMode.SAME_THREAD)`.
 
 [discussion-id]`9F6A7015-9AD8-43DC-AC68-CC6D66C5212F`

articles/testing/end-to-end/bdd.adoc

@@ -28,46 +28,51 @@ pass:[<!-- vale Vaadin.FirstPerson = YES -->]
 This kind of formalization is realized in the JBehave BDD framework for Java.
 The TestBench Demo includes a JBehave example, where the above scenario is written as the link:https://github.com/vaadin/testbench-demo/blob/master/src/test/java/com/vaadin/testbenchexample/bdd/CalculatorSteps.java[following test class]:
 
-
+[.example]
+--
 [source,java]
 ----
-public class CalculatorSteps extends TestBenchTestCase {
-    private WebDriver driver;
-    private CalculatorPageObject calculator;
-
-    @BeforeScenario
-    public void setUpWebDriver() {
-        driver = TestBench.createDriver(new FirefoxDriver());
-        calculator = PageFactory.initElements(driver,
-                CalculatorPageObject.class);
-    }
+<source-info group="CalculatorSteps.java"></source-info>
+public class CalculatorSteps extends ChromeSteps {
 
-    @AfterScenario
-    public void tearDownWebDriver() {
-        driver.quit();
-    }
+    private KeypadElement calculator;
 
-    @Given("I have the calculator open")
-    public void theCalculatorIsOpen() {
-        calculator.open();
+    @BeforeScenario
+    public void setElements() {
+        calculator = $(KeypadElement.class).first();
     }
 
     @When("I push $buttons")
     public void enter(String buttons) {
-        calculator.enter(buttons);
+        calculator.calculate(buttons);
     }
 
     @Then("the display should show $result")
     public void displayShows(String result) {
-        assertEquals(result, calculator.getResult());
+        assertEquals(result, calculator.getDisplayValue());
     }
 }
 ----
+[source,java]
+----
+<source-info group="ChromeSteps.java"></source-info>
+// extend TestBench helper class for extra testing features
+public class ChromeSteps extends AbstractBrowserDriverTestBase {
+
+    // open webpage before test
+    @BeforeScenario(order = 100)
+    public void beforeScenario() {
+        getDriver().get("http://" + IPAddress.findSiteLocalAddress() + ":8080");
+    }
+
+}
+----
+--
 
 The demo employs the page object defined for the application UI, as described in <<page-objects#,Creating Maintainable Tests using Page Objects>>.
 
-Such scenarios are included in one or more stories, which need to be configured in a class extending `JUnitStory` or `JUnitStories`.
-In the example, this is done in the https://github.com/vaadin/testbench-demo/blob/master/src/test/java/com/vaadin/testbenchexample/bdd/SimpleCalculation.java class.
+Such scenarios are included in one or more stories, which need to be configured in a class extending `JupiterStories`.
+In the example we use TestBench to manage `WebDriver` and browser configuration, this is done in the link:https://github.com/vaadin/testbench-demo/blob/master/src/test/java/com/vaadin/testbenchexample/bdd/SimpleBDDCalculationIT.java[SimpleBDDCalculationIT.java] class.
 It defines how story classes can be found dynamically by the class loader and how stories are reported.
 
 For further documentation, see the JBehave website at https://jbehave.org/.

articles/testing/end-to-end/ci-server.adoc

@@ -46,7 +46,7 @@ If you aren't using site local addresses (10.x.y.z, 172.16.x.y or 192.168.x.y),
 == Making Sure the Browsers Are Available
 When running the tests on your local machine, you need to have a suitable browser installed.
 If the test creates a `ChromeDriver` instance, you need to have Chrome installed, and so on.
-The same goes for the CI server (the build agent) if you are running tests directly on a local browser (as opposed to a test cluster, described in <<multiple-browsers#,Running Tests on Multiple Browsers in a Grid>>).
+The same goes for the CI server (the build agent) if you are running tests directly on a local browser (as opposed to a test cluster, described in <<multiple-browsers#,Running Tests on Multiple Browsers>>).
 
 In addition to installing the browsers on the build agent, you must consider the fact that browsers typically require a GUI to be run.
 This isn't available directly on your typical build system.

articles/testing/end-to-end/creating-tests.adoc

@@ -83,8 +83,11 @@ You can use the `ElementQuery` instance returned by [methodname]`$()` to refine
 
 Using Element Queries and Elements you can now compose test methods like:
 
+[.example]
+--
 [source,java]
 ----
+<source-info group="JUnit 4"></source-info>
 @Test
 public void fillForm() {
     $(TextFieldElement.class).id("firstName").setValue("John");
@@ -93,6 +96,18 @@ public void fillForm() {
     Assert.assertEquals("Thank you for submitting the form", $(DivElement.class).id("result"))
 }
 ----
+[source,java]
+----
+<source-info group="JUnit 5"></source-info>
+@BrowserTest
+public void fillForm() {
+    $(TextFieldElement.class).id("firstName").setValue("John");
+    $(TextFieldElement.class).id("lastName").setValue("Doe");
+    $(ButtonElement.class).id("ok").click();
+    Assertions.assertEquals("Thank you for submitting the form", $(DivElement.class).id("result"))
+}
+----
+--
 
 Do be aware that if you write tests in this manner, you can have a hard time maintaining the tests.
 A good way to structure tests is to have only the high-level logic in the test itself (your manager should be able to read and understand the test method) and extract the `ElementQuery` parts to a separate *Page Object* class.

articles/testing/end-to-end/getting-started.adoc

@@ -12,14 +12,28 @@ The tests are automatically executed on your local Chrome when you run `mvn veri
 == Setting Up Your Project
 To start using TestBench in an existing project, you need to add the TestBench dependency (`com.vaadin`/`vaadin-testbench`) with a `test` scope.
 Assuming you have imported the Vaadin Bill-of-Materials (BOM) and have a Maven project, all you need to do is add:
+
+[.example]
+--
 [source,xml]
 ----
+<source-info group="JUnit 4"></source-info>
 <dependency>
     <groupId>com.vaadin</groupId>
     <artifactId>vaadin-testbench</artifactId>
     <scope>test</scope>
 </dependency>
 ----
+[source,xml]
+----
+<source-info group="JUnit 5"></source-info>
+<dependency>
+    <groupId>com.vaadin</groupId>
+    <artifactId>vaadin-testbench-junit5</artifactId>
+    <scope>test</scope>
+</dependency>
+----
+--
 The `test` scope and version number are predefined by the Vaadin BOM.
 
 To be able to run tests locally, you might need to install a WebDriver for your browser.
@@ -29,7 +43,7 @@ See <<installing-webdrivers#,Installing WebDrivers>> for more details.
 
 The fundamental parts of any TestBench test are:
 
-1. Create an instance of the browser driver for the browser you want to use
+1. Create an instance of the browser driver for the browser you want to use (by default, TestBench uses Chrome browser driver)
 2. Open the URL containing the application you want to test
 3. Perform test logic and assert that the result was the expected one
 4. Close the driver instance to close the browser
@@ -39,8 +53,11 @@ If you are adding this test to your own custom application, it fails unless you
 
 In the Maven world, all test classes live in the `src/test/java` directory. Create a new class called `SimpleIT` in that directory (`IT` stands for *integration test* and Maven automatically runs all `*IT` classes):
 
+[.example]
+--
 [source,java]
 ----
+<source-info group="JUnit 4"></source-info>
 import org.junit.After;
 import org.junit.Assert;
 import org.junit.Before;
@@ -76,6 +93,41 @@ public class SimpleIT extends TestBenchTestCase {
 
 }
 ----
+[source,java]
+----
+<source-info group="JUnit 5"></source-info>
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.BeforeEach;
+
+import com.vaadin.testbench.BrowserTest;
+import com.vaadin.testbench.BrowserTestBase;
+
+public class SimpleIT extends BrowserTestBase {
+
+    @BeforeEach
+    public void setup() throws Exception {
+        // Open the application
+        getDriver().get("http://localhost:8080/");
+    }
+
+    // Please note that since TestBench 9 test methods
+    // must be annotated with helper @BrowserTest annotation.
+    @BrowserTest
+    public void clickButton() {
+        // Find the first button (<vaadin-button>) on the page
+        ButtonElement button = $(ButtonElement.class).first();
+
+        // Click it
+        button.click();
+
+        // Check that text of the button is "Clicked"
+        Assertions.assertEquals("Clicked", button.getText());
+    }
+
+}
+----
+--
 
 This is all you need to verify that the text of the button is "Clicked" after clicking on it.
 

articles/testing/end-to-end/maven.adoc

@@ -71,8 +71,11 @@ See the Bakery starter for JavaEE (at the time of writing only available for Vaa
 
 In Maven, unit tests are executed by the `maven-surefire-plugin`, automatically included in all projects.
 Integration tests are executed by the `maven-failsafe-plugin` instead, which needs to be included manually in the project as
+[.example]
+--
 [source,xml]
 ----
+<source-info group="JUnit 4"></source-info>
 <plugin>
     <groupId>org.apache.maven.plugins</groupId>
     <artifactId>maven-failsafe-plugin</artifactId>
@@ -90,9 +93,31 @@ Integration tests are executed by the `maven-failsafe-plugin` instead, which nee
     </configuration>
 </plugin>
 ----
+[source,xml]
+----
+<source-info group="JUnit 5"></source-info>
+<plugin>
+    <groupId>org.apache.maven.plugins</groupId>
+    <artifactId>maven-failsafe-plugin</artifactId>
+    <version>3.0.0-M7</version>
+    <executions>
+        <execution>
+            <goals>
+                <goal>integration-test</goal>
+                <goal>verify</goal>
+            </goals>
+        </execution>
+    </executions>
+    <configuration>
+        <trimStackTrace>false</trimStackTrace>
+        <rerunFailingTestsCount>3</rerunFailingTestsCount>
+    </configuration>
+</plugin>
+----
+--
 
 The `<executions>` part is needed to actually execute the plugin during the `integration-test` phase.
-The `<configuration>` part is optional but, by including it, you get the full stack trace when an error occurs, which typically makes it easier to figure out what went wrong in a test.
+The `<configuration>` part is optional but, by including it, you get the full stack trace when an error occurs, which typically makes it easier to figure out what went wrong in a test. Running failed tests multiple times is also possible using the `rerunFailingTestsCount` property.
 
 == Downloading WebDrivers Automatically
 The `driver-binary-downloader-maven-plugin` plugin downloads WebDrivers for a given browser and platform and makes them available for the TestBench tests.