(refactor) Service: Enhance the functionality of the services.

[hastebrot]

• finder.NodeFinder needs to be able to return invisible Nodes. Introducing a NodeQuery could help to keep the interface simple ((feat) Service: Implement NodeQuery. #174, (refactor) Service: Make NodeFinder more familiar to JavaFX developers. #205).
• finder.WindowFinder needs to be able to accept Nodes in target() and window() ((refactor) Rename window methods to targetWindow(), listWindows(), and window(). #238).
• locator.PointLocator needs to be able to return coordinates relative to the Scene and the Screen ((refactor) API: Rename pointFor() to point() and add pointOfVisibleNode(). #194, (refactor) Service: Introduce BoundsQuery and refactor PointQuery. #206).
• support.CaptureSupport needs to be able to capture certain Bounds, draw Rectangles into the Images and add text of AssertionError to the Images.
• support.WaitUntilSupport needs to be able to use WaitForAsyncUtils instead of the deprecated FXTestUtils.

[hastebrot]

clickOn(".button");
verifyThat(".button", isEnabled()); // Matcher<Node>
verifyThat(".button", hasItem(isEnabled()); // Matcher<Iterable<Node>>
verifyThat(".button", everyItem(isEnabled()); // Matcher<Iterable<Node>>

// FxRobot:
void clickOn(String selector) { // pointFor(String selector)
    // queryFirst() throws a NodeQueryException that gives the matcher's descriptions 
    // and states how many items were matched by them. If throwIfEmpty() was omitted
    // then queryFirst().get() will throw an IllegalStateException.
    NodeQuery nodeQuery = nodeFinder()
        .from(rootsOfWindows(windowFinder().allWindows()))
        .lookup(bySelector(selector))
        .match(isVisible());
    clickOn(nodeQuery.throwIfEmpty().queryFirst().get());
}

// FxRobot:
void clickOn(String selector) {
    NodeQuery nodeQuery = nodeFinder().node()
        .from(rootsOfWindows(windowFinder().allWindows()))
        .lookup(bySelector(selector));
    // if (visibleNodeQuery.queryAll().isEmpty()) { throw new FxRobotException()) }
    NodeQuery visibleNodeQuery = nodeFinder().node()
        .from(nodeQuery.queryAll())
        .match(isVisible());
    clickOn(visibleNodeQuery.queryFirst().get());
}

// FxAssert:
void verifyThat(String selector, Matcher<Node> matcher) {
    // queryFirst().orNull() does not throw an Exception, since throwIfEmpty() was 
    // omitted. verifyThat() throws an AssertionError and uses matcher for description.
    NodeQuery nodeQuery = nodeFinder()
        .from(rootsOfWindows(windowFinder().allWindows()))
        .lookup(bySelector(selector));
    verifyThat(nodeQuery.queryFirst().orNull(), matcher);
}

// FxAssert:
void verifyThat(String selector, Matcher<Iterable<Node>> matcher) {
    NodeQuery nodeQuery = nodeFinder()
        .from(rootsOfWindows(windowFinder().allWindows()))
        .lookup(bySelector(selector));
    verifyThat(nodeQuery.queryAll(), matcher);
}

TODO: Create screenshots and add a note to the matcher descriptions.

---

query().from(verifyThatNode).queryFirst();

query().from(rootOfPopupControl(popupControl))
       .lookup(bySelector(".color-square"))
       .match(isColorSquareWith(Color.RED)) // NoNodesFoundException?
       .match(isVisible()) // NoNodesVisibleException?
       .queryFirst();

query().from(tableView)
       .lookupAt(rowIndex, bySelector(".table-row-cell"))
       .lookupAt(columnIndex, bySelector(".table-cell"))
       .match(isVisible())
       .queryFirst();

Reference: http://en.wikipedia.org/wiki/Monotonicity_of_entailment

[hastebrot]

FxRobot provides node(String selector), point(String selector) and moveTo(String selector).

• node() and node(...) return a NodeQuery that provides queryFirst() and queryAll().
• point(...) and offset(...) return a PointQuery that provides query(). They should use node().queryFirst() where appropriate and throw an FxRobotException, if no Nodes were found.
• moveTo(...) returns void. It internally uses visiblePoint(String selector) which in turn uses node(String selector). It should check if Nodes were found and filter visible Nodes. It should call queryFirst() and throw an FxRobotException that gives a precise message if no Nodes were found. moveTo(Node) does not need node() but should also verify that Node is visible.

FxRobotException: Could not calculate target point.
(no visible Nodes to interact with were found)
The selector "#button" returned 1 nodes, but none was visible.

FxRobotException: Could not calculate target point.
The predicate returned 5 nodes, but none was visible.

FxRobotException: Could not calculate target point.
The node query returned 0 nodes.