Visual test automation: Galen tests and Java (Part 2 of "mobile native")

First things I needed to do for my "let's try to do visual test automation of mobile native apps using Galen" project:
- to understand how Galen Framework is working with "normal" web sites;
- learn to call it from my Java tests;
- ensure Java Page Object model can be used and @objects descriptions can be removed from Galen specs. We need this to keep objects described only once and in single place so that they could be used for both Galen and functional tests.

I've used resources provided by Galen Framework - sample Galen Java tests and sample web site for those tests as a starting point. To run the web site locally on my PC I've used a very simple Fenix webserver (Galen Framework provides public access to the test website, but I prefer to use local copy for my experiments). The only change I've made initially - updated tests to use Chrome browser instead of default Firefox; it's so much less problems running tests this way at the moment.

Galen tests from Java are run as regular TestNG tests. At the time I think everything I knew about TestNG was "it exists and works". As focus was on Galen and Java Page Objects integration, I decided to skip learning anything about TestNG configuration, test suites etc. for a while. Simple "click and run" from IntelliJ was enough for this.

Well, first surprise: it just worked! I was a bit sceptical about this - sample tests and site were updated few years ago, in my experience usually this means "thing is forgotten, update it if you need it now". I had to adjust site pages a bit, as something in "site without errors" and "site with errors" samples is  mixed up, but it's almost not worth mentioning it. Galen Framework earned a first "huge plus" - the samples they provide are working.

Now to the most complicated part - try to modify those sample tests and use Java Page Objects. Remember - I'm new to Java, so everything takes much more time than for experienced Java developer. The first challenge - I was not able to find almost any "human understandable" info on how Galen Framework works. I do agree that for more experienced Java developer javadocs and source code is enough. Well, it took some time for me to learn to use those. I hope this blog post will help others who are trying to do similar things with Galen framework as I did.

First thing to understand - checkLayout in GalenJavaTestBase class is the main thing which interests you. This is analogue of assertAll in other kinds of test - it checks everything you have written as Galen specification in spec file and provides info for reporting. Call to Galen.checkLayout in this method goes deep into other "check layout" calls and finally does the actual work. So those two are things which should get knowledge about Java page objects and be able to use them.

For simple first experiment I've use common.spec Galen specification file. Original file has following objects descriptions:

@objects
    header                   css   #header .middle-wrapper
    header-logo              id    header-logo
    header-text              css   #header h1
    menu                     css   #menu ul
    menu-item-*              css   #menu li a
    content                  css   #content
    footer                   id    footer

First trying simplest possible change: I removed only a single thing - header object specification. After doing this @objects part of original file looks like this:

@objects
    header-logo              id    header-logo
    header-text              css   #header h1
    menu                     css   #menu ul
    menu-item-*              css   #menu li a
    content                  css   #content
    footer                   id    footer

Everything else exactly the same as in original sample test specification (which I already know is working as expected), only one object description is missing.

Now I needed to do something with all those checkLayout: create something in Java which would be analogue to the header object specification I've removed from Galen spec. Then I needed to pass this "something" to checkLayout.

After diving into Galen Framework source code I've found out, that everything from @objects in Galen spec file is used as a map of Galen locators, so I added this to sample WelcomePageTest.java file:

Map<String, Locator> galenLocators = new HashMap<>();

To use this, I modify original sample welcomePage_shouldLookGood_onDevice test:

    @Test(dataProvider = "devices")
    public void welcomePage_shouldLookGood_onDevice(TestDevice device) 
                                                    throws IOException {
        load("/");
        galenLocators.put("header", Locator.css("#header .middle-wrapper"));
        checkLayout("/specs/welcomePage.spec", device.getTags(), galenLocators);
    }

Another simplest minimal change: added header I've removed from Galen spec file to my Java code and expect the test results will be the same as before removal. From the original spec file I know header is located using CSS locator, so I do the same in my Java code.

Now the final part - I needed checkLayout which could accept this galenLocators map as parameter and would know how to use it.

At this point I don't care too much about code structure, it's just a proof of concept. So I add custom checkLayout to the same welcomePageTest class.

    public void checkLayout(String specPath, List<String> includedTags, Map<String, Locator> galenLocators) throws IOException {
        String title = "Check layout " + specPath;
        SectionFilter sectionFilter = new SectionFilter(includedTags, Collections.emptyList());
        Browser browser = new SeleniumBrowser(this.getDriver());
        LayoutReport layoutReport = Galen.checkLayout(browser, specPath, sectionFilter, new Properties(), (Map)null, null, null, galenLocators);
        this.getReport().layout(layoutReport, title);
        if (layoutReport.errors() > 0) {
            throw new LayoutValidationException(specPath, layoutReport, sectionFilter);
        }
    }

This is a slight modification of best matching my goals checkLayout method and calling correct Galen.checkLayout method from list of available methods. They both use the map of galenLocators I've created in previous steps.

No another test code changes, no Java page objects at the moment. Run the test and see if idea works. Well, it worked!

Now I was sure I have a working checkLayout which accepts galenLocators map as parameter. As this will be needed by other tests, moved it to GalenTestBase class.

Came time to create Java page objects and use them. This involved some other challenges understanding how Galen works from Java point of view, what can and what cannot be done while trying to remove @object descriptors from spec file. Will move it to another post.

---

This is second post in series "Adventures trying to automate visual testing of mobile native apps using Galen Framework". Previous post can be found here:

- Visual test automation: mobile native (Part 1)