Update docs for recent ATH improvements
@@ -35,6 +35,20 @@ mvn clean install -DskipTests -DcleanNode
This is mainly for CI servers. It starts the selenium docker container and runs all
nightwatch and java ATH tests in one shot.
+### Run tests against a local instance
+
+ATH looks for a properties file at `~/.blueocean-ath-config` (or any combination of similar command line options).
+These options will allow you to run a local [ChromeDriver](https://sites.google.com/a/chromium.org/chromedriver/),
+ for example, and execute the ATH against a local development instance
+that you can debug/etc.. Currently these properties are supported and/or necessary:
+```webDriverType=chrome
+webDriverUrl=http://localhost:9515
+webDriverBrowserSize=1024x768
+jenkinsUrl=http://localhost:8080/jenkins
+adminUsername=admin
+adminPassword=admin
+```
+
### Run tests in DEV mode
DEV mode starts Jenkins and the selenium docker container running in a standalone mode.
@@ -79,6 +93,8 @@ Running tests via the IDE works as expected as long as the standalone part of th
To start a test in Intellij the easiest way is to right click on the test class or method and click Run test.
+NOTE: if you have a `~/.blueocean-ath-config` it will be used when running tests this way.
+
#### JavaScript [nightwatch] tests.
Nightwatch tests can be run via the nightwatch npm package (`npm install -g nightwatch`). It is
@@ -108,6 +124,38 @@ nightwatch src/test/js/
Make sure you add the acceptance-tests to your intellij blueocean project by right-clicking on `acceptance-tests/pom.xml`
and adding it to the project.
+### WebDriverMixin
+
+There is a `WebDriverMixin` that can help simplify writing tests significantly. It offers a number of
+utility methods for the most common operations, all which have logic added to deal with common problems
+in Blue Ocean such as animation.
+
+It is recommended you use this when writing tests.
+
+A simple example:
+
+```java
+import io.blueocean.ath.WebDriverMixin;
+
+public class LoginTest implements WebDriverMixin {
+ @Test
+ public void login() {
+ // go: goes to a relative jenkins path or absolute if starts with http(s)://
+ go("/login");
+ // find: waits for elements to be preset, if starts with / uses xpath, otherwise CSS selectors
+ find("#j_username") // find by ID when starts with #, this is just a CSS selector
+ // setText: clears, sets text on an input
+ .setText("admin");
+ find("input[name=j_password]") // just a CSS selector
+ .setText("admin");
+ // click: handles animation, failures will retry up to 2 times
+ click("//form[@name='login']//button"); // XPath selector
+ // other utilities, see io.blueocean.ath.WebDriverMixin
+ assert find("//a[contains(@href, 'logout')]").isVisible() : "Not logged in";
+ }
+}
+```
+
#### JUnit4 Tests
All test code is uses Guice to do dependency injection.
