Updated instructions on how to run TB3+ tests with Intellij; added Qu… (#11580)

* Updated instructions on how to run TB3+ tests with Intellij; added QuickStart to quickly set up testing environment

* Readme rewording

1 files changed, 75 insertions, 24 deletions

diff --git a/README-TESTS.md b/README-TESTS.md
index fbaf7d8c19..d79dc8c1ed 100755
--- a/README-TESTS.md
+++ b/README-TESTS.md
@@ -1,12 +1,79 @@
 # TestBench tests in Vaadin Framework
-## Project setup
-The project currently supports running TestBench 3+ (java) tests. Each test consists of a Vaadin UI class and a TestBench script/java test.
 
-All test UI classes go into `uitest/src`. These files are automatically packaged into a war file which is deployed to a Jetty server during the build process so that tests can open and interact with the UI:s. For development purposes, the Jetty server can be started in Eclipse, see running tests in Eclipse.
+The project currently supports running TestBench 3+ (java) tests. Each test consists of two files:
 
-The project is setup so that `/run` is mapped to a specialized servlet which allows you to add the UI you want to test to the URL, e.g. http://localhost:8888/run/com.vaadin.tests.component.label.LabelModes or just http://localhost:8888/run/LabelModes if there are no multiple classes named LabelModes. Because of caching, the ?restartApplication parameter is needed after the first run if you want to run multiple test classes.
+* A TestBench-based Java JUnit test; so-called TB3+ test.
+* A Vaadin UI class which contains the component under test.
 
-## Creating a new test
+The Java JUnit test uses TestBench/Selenium/browser and therefore needs an UI to connect to; that UI
+is provided by the appropriate Vaadin UI class.
+
+All test UI classes go into `uitest/src`. These files are automatically packaged into a war file which is deployed to a Jetty server during the build process so that tests can open and interact with the UI:s. For development purposes, the Jetty server can be started (both in Eclipse, Intellij and from command-line), see running tests in Eclipse.
+
+The project is setup so that `/run` is mapped to a specialized servlet which allows you to add the UI you want to test to the URL, e.g. [http://localhost:8888/run/com.vaadin.tests.component.label.LabelModes](http://localhost:8888/run/com.vaadin.tests.component.label.LabelModes) or just [http://localhost:8888/run/LabelModes](http://localhost:8888/run/LabelModes) if there are no multiple classes named LabelModes. Because of caching, the `?restartApplication` parameter is needed after the first run if you want to run multiple test classes.
+
+# QuickStart: Running one test
+
+The test logic code resides in the TB3+ JUnit tests. However the tests need a webserver to connect to. Read below
+on how to run such a webserver.
+
+## Starting the WebServer: Hosting your UI class in Jetty
+
+Prior running your TB3+ JUnit tests, we need to have the webserver
+hosting testing UI classes up and running. See below for instructions for particular IDEs; the
+instructions for a pure command-line approach are also present.
+
+### Eclipse
+
+The Jetty included in the project can be started in Eclipse by running the “Development Server (Vaadin)” launch configuration in `/eclipse` (right click -> Debug as  -> Development Server (Vaadin) ). This deploys all the tests to `localhost:8888` (runs on port 8888, don’t change that unless you want problems). Use `/run/<uiclass>` to open a test.
+
+The DevelopmentServerLauncher has a built-in feature which ensures only one instance can be running at a time. There is therefore no need to first stop the old and and then start a new one. Start the server and the old one will be killed automatically.
+
+### Command-line
+
+```bash
+cd uitest
+mvn jetty:run-exploded
+```
+
+The server should now be running at port 8888. Every testing UI class
+is published as [http://localhost:8888/run/&lt;testUI&gt;](http://localhost:8888/run/<testUI>).
+For example you can see the testing UI for the `GridEditorTabSkipsNonEditableCellsTest` here: [http://localhost:8888/run/GridEditorTabSkipsNonEditableCells](http://localhost:8888/run/GridEditorTabSkipsNonEditableCells).
+
+### Intellij
+
+We're going to do the same as with the command-line approach - launch the `mvn jetty:run-exploded`:
+
+1. Open *Maven Projects*
+1. Open *vaadin-uitest* -> *Plugins* -> *jetty* -> *jetty:run-exploded*
+1. Open URL [http://localhost:8888/run/&lt;testUI&gt;](http://localhost:8888/run/<testUI>)
+
+## Setup before running any tests from your IDE
+
+Before running any tests from your IDE you need to
+1. copy `uitest/eclipse-run-selected-test.properties` to `work/eclipse-run-selected-test.properties`
+2. edit `work/eclipse-run-selected-test.properties`
+    1. Define `com.vaadin.testbench.screenshot.directory` as the directory where you checked out the screenshots repository (this directory contains the “references” subdirectory)
+    2. Set `com.vaadin.testbench.deployment.url=http://localhost:8888/`
+    3. Set `com.vaadin.testbench.runLocally=chrome` to only run tests on Chrome. On Ubuntu you can then install Chrome driver easily:
+       `sudo apt install chromium-chromedriver`
+
+> Note: the file is named `eclipse-*` but it applies to all IDEs.
+
+## Running TB3+ tests
+
+Now that the UI Jetty server is up and running and the `work/eclipse-run-selected-test.properties` file is properly created,
+you can run the actual tests.
+
+TB3+ tests are standard JUnit tests which can be run using the “Run as -> JUnit test” (or Debug as) in Eclipse or Intellij.
+Right click on a single test instance in the JUnit result view and select to debug to re-run it on a single browser.
+
+As an example, you can find the `GridEditorTabSkipsNonEditableCellsTest` JUnit test,
+right-click the class and chose "Run As JUnit test".
+
+Done: your environment is set up properly. Now you can proceed to writing your own tests.
+
+# Creating a new test
 Creating a new test involves two steps: Creating a test UI (typically this should be provided in the ticket) and creating a TestBench test for the UI.
 
 ## Creating a new test UI
@@ -95,27 +162,11 @@ Use ids in your UI class. Define the IDs as constants in the UI class. Use the c
             assertAltText(NativeButtonIconAndText.BUTTON_TEXT, "");
 
 
-## Running the DevelopmentServerLauncher
-
-The Jetty included in the project can be started in Eclipse by running the “Development Server (Vaadin)” launch configuration in `/eclipse` (right click -> Debug as  -> Development Server (Vaadin) ). This deploys all the tests to `localhost:8888` (runs on port 8888, don’t change that unless you want problems). Use `/run/<uiclass>` to open a test.
-
-The DevelopmentServerLauncher has a built-in feature which ensures only one instance can be running at a time. There is therefore no need to first stop the old and and then start a new one. Start the server and the old one will be killed automatically.
-## Setup before running any tests in Eclipse
-
-Before running any tests in Eclipse you need to
-1. copy `uitest/eclipse-run-selected-test.properties` to `work/eclipse-run-selected-test.properties`
-2. edit `work/eclipse-run-selected-test.properties`
-    1. Define `com.vaadin.testbench.screenshot.directory` as the directory where you checked out the screenshots repository (this directory contains the “references” subdirectory)
-
-## Running TB3+ tests
-
-TB3+ tests are standard JUnit tests which can be run using the “Run as -> JUnit test” (or Debug as) in Eclipse. Right click on a single test instance in the JUnit result view and select to debug to re-run it on a single browser.
-
-### Debugging TB3+ tests
+## Debugging TB3+ tests
 
-#### Debugging remotely
+### Debugging remotely
 Running remotely on a single browser (as described above) can be used to debug issues with a given browser but with the downside that you cannot see what is happening with the browser. In theory this is possible if you figure out on what machine the test is run (no good way for this at the moment) and use VNC to connect to that.
-#### Debugging locally
+### Debugging locally
 A better option is to run the test on a local browser instance. To do this you need to add a `@RunLocally` annotation to the test class. `@RunLocally` uses Firefox by default but also supports other browsers using `@RunLocally(CHROME)`, `@RunLocally(SAFARI)`, `@RunLocally(Browser.IE11)` and `@RunLocally(PHANTOMJS)`.
 
 By default using `@RunLocally` annotation in Framework tests is not allowed. In order to run a test locally, you need to uncomment the line `com.vaadin.testbench.allowRunLocally=true` in `work/eclipse-run-selected-test.properties`.