Archives

Category: gwen-web

BrowserStack allows you to run automated Selenium tests on a variety of platforms, browsers, and devices on the cloud. Since Gwen is built on Selenium and also supports remote web driver, you can easily run your Gwen tests “as is” on BrowserStack too. As of gwen-web version 2.25.1, all you need to do is provide some runtime properties.

Remote URL

If you sign up for a BrowserStack account, you will receive a user name and access key. Add the following settings to your gwen.properties file to configure your connection to BrowserStack:

Target Capabilities

BrowserStack provides a neat capabilities page that can generate capabilities settings for you. Simply navigate to that page and select your desired target platform and browser. The capabilities settings will be generated for you and displayed as shown below:

This example shows the capabilities settings for a Chrome browser on the Mac OS X High Sierra Platform. To configure Gwen to use these settings, create a new properties file containing each of the settings above as follows:

You can save this file anywhere you like. For example, you could save it in your current working directory as chrome-mac.properties.

You can create a separate properties file in the same manner for each other platform, browser, or device you wish to target.

Execution

Now to run your Gwen features on BrowserStack, simply invoke Gwen passing in the above properties file (through the -p option) as follows. This example will run all features in the features/google folder on BrowserStack targeting the Chrome browser on the Mac.

./gwen -b -p chrome-mac.properties features/google

To target a different platform or browser, just pass in the properties file containing those capabilities instead.

If you logon to browserstack.com, you will see the results of all the remotely executed web driver steps and a video recording of the feature execution too.

Declarative Features

From a business perspective, feature specifications should be declarative. What does does this mean? It means that features should describe the intended behavior of a feature independently of any implementation details (especially automation details). They should clearly express behavior in business terms and may also include some examples.

Imperative Features

Imperative specifications on the other hand consist of a step by step list of statements that describe a behavior in great detail and that can be followed robotically to emulate a process. You would ideally never write features in this manner when describing business specifications.

Meta Features

Declarative to Imperative Automation Bindings

Gwen is a Gherkin interpreter that was designed with behavior driven automation (BDA) in mind. It enables teams to bind declarative business features “as is” to imperative meta features to drive automation. Meta features are used to describe (or break down) declarative features into step definitions and bindings that can be used to drive automated testing and robotic processing. In Gwen, they are also defined in the Gherkin language and bind to declarative features at run time to make them executable.

Reuse can be maximised by sharing common meta across features

Test-First

In the test-first approach, the team would first write feature specifications and then use those to drive development and automated testing at the same time. Executing features with Gwen prior to development would result in failures (as expected). As the feature is being implemented in code, the developers and/or testers can write meta features to define all the necessary step definitions and bindings. Loading the meta and executing features with Gwen during development would then enable the test execution to run. By progressively building up the required meta during development, the feature tests will eventually pass when implementation is complete.

Test-Later

In the test-later approach, Gherkin features can be used to drive user acceptance testing after the development is complete. New acceptance features can be written if desired at this stage. Any meta that was created during development (if the test-first approach was practiced) could be reused here. Otherwise all the necessary step definitions and bindings will need to be defined in meta during this phase. The meta can then be loaded into Gwen to make the acceptance features perform the test execution.

Robotics

Robotic process automation (RPA) involves the repeatable execution of tasks that would otherwise need to be performed by humans. A repetitive or monotonous process performed online by a person, for example, can be automated with Gwen by writing Gherkin specifications that describe that behavior. These too can be declarative with imperative bindings in meta, but can also be imperative only.

Gwen Engines

We have open sourced a web engine (Selenium wrapper) for Gwen that you can use to perform any sort of web UI automation using the approaches described above. But Gwen is not limited to just web automation. Many types of Gwen engines can be built and shared. We are currently developing a REST engine for API testing and automation.

Gwen is first and foremost a BDA tool. BDD on the other hand has its purpose but it’s not automation. It’s a development practice. But it turns out that behavior in prose can be used to drive automation.

When you use behavioral specifications to drive automation of any kind, you are doing BDA. Be it for testing, robotic process automation (RPA) or any other purpose. It does not matter!

It just so happens that in BDD you are doing it to test-first at development time. In the case of test-later and also RPA, you are doing it after development time. Gwen can be used to transform behavioral specifications into automation operations in any case.

Copy any common Gwen meta files required by all features to the meta folder (optional)

Check that your features execute successfully by running gwen features -b in the workspace root

You can tweak any Gwen properties or wrapper scripts in the workspace if required to tailor your execution.

Publish your workspace folder to your Git repository

The benefit of using a workspace is that it contains an embedded Gwen Package Manager that will automatically install Gwen and any native web drivers for you (so you don’t have to do this manually in the Jenkins environment). If you do not want to use a workspace but would rather utilise your current project setup “as is”, then you will have to do manual installation and configuration work on the Jenkins host to ensure that your features can execute (but the basic setting up of the Jenkins job will be similar to below).

Create a Jenkins Job

Once you have a workspace that is accessible from Git, you are ready to create a Jenkins job to run your workspace.

In the “Build” section, select “Execute Shell” (for linux) or “Execute Windows Batch Command” (for windows), and enter the following command to run Gwen

Linux: ./gwen features -b -f junit -Dgwen.web.browser.headless=true

Windows: gwen features -b -f junit -Dgwen.web.browser.headless=true

-b tells Gwen to exit once execution is complete, -f junit tells Gwen to generate JUnit-XML reports, and -Dgwen.web.browser.headless=true tells Gwen to run the browser in headless mode. You can also pass additional Gwen options if required, like --parallel for example if you want to utilise all cores and perform parallel execution.

In the “Post-build Actions” section, select “Publish JUnit test result report”, and enter the following in the “Test Report XMLs” field.

Manually setting up and installing Gwen on multiple machines or build servers in a team environment can be tedious and can also result in inconsistent configurations across workstations. One of the reasons why we created gwen-gpm was to provide consistent installation across machines and platforms. But a team needs more than that. A team needs a consistent and seamless way of getting Gwen configured and running on any user workstation or build server too.

Introducing Gwen workspaces

Gwen workspaces solve this problem by defining a standard project structure on the file system complete with settings files and wrapper scripts that can easily be committed to Git and checked out on any machine. Any team member can then just checkout the workspace and start using Gwen straight away. Gwen and the native web drivers will be automatically downloaded and installed on any user workstation or build server if they are not already present (through an embedded Gwen package manager in the workspace).

It is assumed that the target browser is already installed on the system. If not, you will need to manually install it. The wrapper script installs Gwen and native drivers but not the browser itself.

Create and Commit a Workspace to Git

To create a Gwen workspace for your team, perform the following (only one person in the team needs to do this):

Download and extract the latest gwen-workspace.zip to a location on your file system. (Also have a read of the README.txt file that is extracted in the root).

Tweak or add team wide settings to the gwen.properties file in the workspace root. You can also tailor the wrapper scripts if necessary (for example, if you want to change the default Gwen launch options or add some new ones).

Verify that it all works by launching gwen (on windows) or ./gwen (on linux). Type exit when done to quit the REPL session.

Commit and push the workspace to your remote Git repository (see online Git help if you are not sure how to do this)

Checkout Workspace from Git and Go..

To use the workspace on any machine, perform the following (all team members need to do this):

Ensure that the target browser is installed on the system

Checkout the workspace from Git

Open a command prompt to the root workspace location

Type..

gwen (on windows) or ./gwen (on linux) followed by the options you require

Gwen will execute using the settings in the workspaceNote: this same command can be used on any build server that checks out the workspace too

Gwen and native web drivers will self install on the first call

Type exit when done to quit the REPL session (if you started Gwen in REPL mode).

The team can now manage all their Gwen settings, environment configurations, Gherkin feature files, and Gwen meta files in a single workspace that can easily be pulled down and executed on any machine.

Help

For help, open a command prompt in the workspace root and type:

gwen help (on windows platforms)

./gwen help (on linux platforms)

Each folder in the workspace also includes a README.txt file that can help to guide you.

Gwen has always had the capability to make use of selenium grid which is particularly useful when running in parallel, and after discovering selenoid by the guys over at Aerokube I had to give it a shot.

Installing selenoid was a breeze with the configuration manager docker setup. Once installed, selenoid downloads the last two driver versions of chrome, firefox and opera, and starts a grid ready to run tests.

Gwen comes with 235 features out of the box, ready for anyone to try. These features cover a number of different scenarios including a flood.io challenge, navigating etsy, completing a todo, navigating blogs, and searching in google. The features are also written using both imperative and declarative styles declarative-vs-imperative-gherkin.

Typically running 235 features takes 49 minutes and 33 seconds when running the features sequentially, however running these in parallel with selenoid took only 4 minutes and 41 seconds. Both samples were run using a 34 core machine.

Gwen running 235 features sequentiallyGwen running 235 features in parallel

I have also included a screenshot of the running docker images, taken at a point in time where parallel was running full swing.

Thats all for now, hope you enjoyed a brief look into Selenoid and Gwen.

Gwen now supports data tables and in this post I’m going to show you some examples of how they can be used with the web engine to automate some repetitive tasks on the TodoMVC web application.

Data tables are handy for when you want to work with lists of items in Gherkin, such as the list of todo items shown in this example below.

File: features/todo/tables/TodoTables.feature

Feature: Managing todo items with data tables
Scenario: Complete a todo item
Given I have the following active items
| Walk the dog |
| Get the milk |
| Feed the cat |
When I complete the "Get the milk" item
Then the status of my items should be
| Item | Status |
| Walk the dog | active |
| Get the milk | completed |
| Feed the cat | active |

Note that this example is a high level (or declarative) feature specification that describes intended behaviour and not a low level (or imperative) list of statements that describe how automation is to be achieved or on what type of system it will be performed on. Those are automation bindings that can be captured in separate meta files that are also expressed in Gherkin when using Gwen. As it turns out, we already have a meta file that specifies some step definitions that call out to predefined steps in the web engine to interact with the TodoMVC app. One of the capabilities of Gwen is the ability to reuse this meta, so we will reuse it here to help compose some step definitions for our data tables above. You can have a look at that Todo.meta file here if you like.

Data Table Bindings

Looking at the first Given step in our feature, we can see that it contains three todo items in a table. The step implies that we have those three items in our todo list. So what we want to do is load those three items into our list in the todo app when running this step. To do that, we need to create a step definition for it that will launch the app, load the items, and verify that they are all active. We can do that with some new meta as follows:

File: features/todo/tables/TodoTables.meta

Feature: TodoMVC tables meta
@StepDef
@DataTable(horizontal="Item")
Scenario: I have the following active items
Given I launch the Todo app
When I add a "${data[1][Item]}" item
And I add a "${data[2][Item]}" item
And I add a "${data[3][Item]}" item
Then the "${data[Item]}" item should be active for each data record

This meta is also a Gherkin specification with a tagged scenario containing all the steps that will perform the desired operations on the data table.

This first @StepDef tag tells Gwen to load this scenario to memory and only execute its steps when a step in a feature references it by name. Note that the name of this scenario is the same expression used in the Given step in the feature. This is how step definitions work in Gwen.

The second @DataTable tag contains an attribute that declares the table to contain horizontal data records and that each one of those contains just one data cell that we will call “Item”. We need to do this since the table in the feature does not include a header record at the top and we have to assign each cell a name so we can access its data by that name.

The steps from lines 7 to 9 load the items one at a time by explicitly referencing the data in each record

The last step on line 10 checks that each item is active by iterating over each record of the table

With this in place and the latest web engine installed, we can now invoke the feature with Gwen as follows.

gwen -b features/todo/tables/TodoTable.feature

Gwen will automatically discover and load the automation bindings in all meta files that exist in the path of the feature file which in our case includes both the Todo.meta we want to reuse and the TodoTables.meta we just created. The Given step in the feature will execute to load the table items and verify that they are all active, and the When step will complete the second item. The Then step in the feature will fail as expected because we haven’t defined a step definition for it yet. The web browser output is shown below:

Similarly, we now add a step definition for the last Then step in our feature to our meta to verify the status of all items and complete all our binding work.

The table in this step includes a header record, so we specify header="top" in the @DataTable tag to link the names in that header to the cells in each data record.

File: features/todo/tables/TodoTables.meta

Feature: TodoMVC tables meta
@StepDef
@DataTable(horizontal="Item")
Scenario: I have the following active items
Given I launch the Todo app
When I add a "${data[1][Item]}" item
And I add a "${data[2][Item]}" item
And I add a "${data[3][Item]}" item
Then the "${data[Item]}" item should be active for each data record
@StepDef
@DataTable(header="top")
Scenario: the status of my items should be
Then the "${data[Item]}" item should be ${data[Status]} for each data record

Now the entire feature is executable!

Simplifying it Further

For the sake of demonstrating explicit table data access, the steps from lines 7 to 9 in our meta process each record one at a time. Imagine if we had a lot more records? There would be a lot of redundancy wouldn’t there? We can remove this by reducing these steps into a single step that loops through each record in the same way that the steps on line 10 and 15 do.

File: features/todo/tables/TodoTables.meta

Feature: TodoMVC tables meta
@StepDef
@DataTable(horizontal="Item")
Scenario: I have the following active items
Given I launch the Todo app
When I add a "${data[Item]}" item for each data record
Then the "${data[Item]}" item should be active for each data record
@StepDef
@DataTable(header="top")
Scenario: the status of my items should be
Then the "${data[Item]}" item should be ${data[Status]} for each data record

Now there is no need to explicitly specify the index for each record when referencing each data cell. But for cases where you might need to cross reference different records or really want to be explicit in how you access each data cell, the earlier approach of not iterating will give you the flexibility you need. It really depends on your particular use case and you should always choose the approach that works the best in the given circumstance.

The feature and meta files created here are available in our samples features/todo/tables folder on Github and are also bundled with the Gwen-web binary distribution. If you download and install it, you can execute the feature in the same way that we did above in your installation directory.

And, that’s it! Our feature with tables is executable and all redundancy has been removed from the bindings. We have mapped declarative feature steps to imperative steps in meta and reused some existing meta too! 🙂