(feat) TextFlowMatchers: Add matchers for the text of a TextFlow.

[brcolow]

Currently there are two ways to match the text contained in a TextFlow.
The first one is based simply off the contained text. The second is
based on the contained text and the color of that text. The expected
colors are encoded in the expected String like:

<COLOR>some text</COLOR>

where COLOR is one of the named colors in JavaFX. For a list of all such
colors, see:

https://docs.oracle.com/javafx/2/api/javafx/scene/doc-files/cssref.html#typecolor

We also extracted out a method for computing the distance between two
colors from PixelMatcherRgb as that functionality was also needed for
finding the color nearest to a named color.

---

I am open to suggestions on a better way to test for colored text in a text flow as I just thought of the simplest thing I could. I could see the TextFlowMatchers being very useful for testing things that mimic
text editor functionality or also in cases where color-coded text helps the user understand the text (for example, using red for negative monetary balances and green for positive monetary balances) and provide better UX.

Let me know what you think!

[hastebrot]

Is it possible to use the CSS color names of javafx.scene.paint.Color directly?

Update: Seems the color names are behind private methods or only retrievable reflection.

Things to consider:

• Does it make sense to have a hasColoredText(TextFlow, String) that matches a color name exactly and a hasColoredText(TextFlow, String, PixelMatcher) to match the color perceptional (or even extract a ColorMatcher from PixelMatcher)?
• Can we implement the functionality using colorName → colorValue (via Color.web(colorName)) instead of colorValue → colorName?

My plan was to implement another PixelMatcher later that uses a better color model than the linear RGB one.

[brcolow]

I think these a really good questions and valid feedback, I will look into them hopefully within the next 24 hours or so. Thanks Benjamin.

Update:

I am not sure how to implement your suggestions given that one could be matching multiple different colors within a single TextFlow. For example, consider the assertion:

assertThat(lookup(#myTextFlow), TextFlowMatchers.containsText("You have insufficient funds. Your available balance is <RED>$5.00</RED> but this action requires <GREEN>$8.00</GREEN>."));

Given that there can be multiple colors to match, I am not sure how a PixelMatcher/ColorMatcher could be used.

Lastly could you please explain a bit more about what you mean by:

Can we implement the functionality using colorName → colorValue (via Color.web(colorName)) instead of colorValue → colorName?

Do you mean having the "markup" look like this:

<ff00ff>Some</ff00ff> text that is <ffffff>colored</ffffff> ?

I think having named colors makes for much more readable assertions, but maybe I misunderstand. Given that we we both agree that having named colors makes for more readable assertions, I do not see how to verify a match any other way than iterating through the list of known named colors and finding the color with the least distance.

I could see creating two different methods:

hasExactlyColoredText(TextFlow textFlow, String string)
hasColoredText(TextFlow textFlow, String string, double minColorDistFactor)

[brcolow]

I updated the PR so that we now have two functions for testing the color of the text of a TextFlow:

hasColoredText:
Given the markup: <COLOR>text</COLOR>
and a TextFlow:

Text text = new Text("text");
text.setFill(someColor);
TextFlow textFlow = new TextFlow(text);

Matches iff the named color that has the least distance from someColor is COLOR.

hasExactlyColoredText:
Given the markup: <COLOR>text</COLOR>
and a TextFlow:

Text text = new Text("text");
text.setFill(someColor);
TextFlow textFlow = new TextFlow(text);

Matches iff someColor and COLOR are both named colors and they have exactly the same RGB values.

I also refactored the named colors ArrayList to a HashMap so that looking up exact color matches is O(1).