Neodymium – An Open Source Framework for Web Testing

TL;DR: Neodymium is a Java-based test library for web automation that utilizes existing libraries (Selenide, WebDriver, Allure, JUnit, Maven) and concepts (localization, test multiplication, page objects) and adds missing components such as test data handling, starter templates, multi-device handling, and other small but useful everyday helpers.

Motivation

As a company focused on quality assurance and testing, Xceptance always needs test automation software, especially end-to-end automation software. Several years ago we built a Firefox add-on that was designed to create and run browser automation. The tool was primarily used by people who didn’t necessarily have a strong background in software development. Today, the landscape is a bit different: Mozilla cut the cord on the APIs we were using and standard programming languages have largely taken over test automation because they are more flexible and less proprietary. These changes convinced us it was time to implement an idea we had already hatched, namely our own Open Source test automation project: Neodymium. It is written in and utilizes the Java platform, it is MIT licensed, and of course you will find it on GitHub: https://github.com/Xceptance/neodymium-library

Basis

There are many libraries out there to aid web automation in Java, so developers are faced with the task of choosing ones they like and somehow making them work together. On top of that, there are tasks that require some custom code to work properly. We identified the overall tooling problem mostly as a hurdle in getting started and setting up a project. Finally, there are always things missing such as test data handling, concurrency, and common patterns which you don’t want to have to develop yourself. We chose JUnit, Selenide, WebDriver, Maven, and Allure for the base tooling.

Selenide provides an easy-to-use API to control Selenium WebDriver. Allure offers good mechanics to generate useful reports based on the assertions and actions you perform throughout your test cases. Maven is used to set up the build and execution environment for our framework and all the test projects. We decided to use JUnit as the test runner since it is the de facto standard in the Java world, but we enhanced the capabilities of JUnit to do even more. At its heart, Neodymium is a JUnit runner that wraps default JUnit behavior and adds significant useful functionality to it.

Multiple Browsers

You want to be able to run the same tests for different resolutions and/or browsers to simulate the browsers most common among your users. Additionally, you need to be able to implement small differences within your test execution to address variants such as responsive designs or progressive web apps. So we added a way to run web browsers with different configurations and retrieve the current device type and resolution from within the test.

Neodymium provides a Java annotation that can be added to your test case, in order to run different browser setups. Neodymium is very flexible in configuring browsers, allowing you to fully leverage the Chrome device emulation offerings.

Test Data

Another common task is the execution of a test case with different data sets, such as testing address forms with all the relevant variations. The basic idea is to have test data and data sets in structured files next to your code, preferably as JSON, XML, property style, or simply CSV. Hence, we introduced an easy-to-use API to access the current data set and retrieve basic types from it. Furthermore, you can configure specific scenarios running only a subset or even no data set at all by adding proper annotations. To complete the picture, Neodymium supports test data on a global and package-level scope.

Localization

Another recurring topic in modern software projects is localization. Most of the web sites that are in need of test automation also support several locales. We decided to provide an out-of-the-box solution.

Neodymium’s localization feature makes use of a central translation file written in YAML format. YAML helps to structure the translations. Additionally, we implemented a simple way to override specific translations for different locales. The localized text can be easily retrieved using Neodymium API methods that are globally available.

Development Support

As it is essential to understand what your test is doing, we added a feature that enables you to slow down the test execution and highlight elements that match the current selector. Since you can chain selectors using Selenide, any chain of elements is also represented by the highlighting. With this feature activated, a developer can track down the cause of test failures much more easily. In addition, we provide information on how to set up logging in your project should you need that. Finally, we decided to use the Page Object pattern to organize the website-related code to reduce the maintenance effort and increase reusability.   

Reporting

Allure is a widely used framework to generate reports. When using Neodymium with Selenide, your automation code also contributes report information. Your test classes and methods are listed as well as detailed Selenide automation commands. In case of errors, additional details such as screenshots and source code of the page in question are available. Neodymium also provides means to structure code blocks for reporting purposes.

Continuous Integration

Implementing principles of continuous integration will deliver more reliable software by increasing efficiency, and automation is nothing without a continuous integration environment.  Yet in almost every development cycle you will eventually end up needing varied settings due to differences in your setup, which can get complicated. Neodymium provides support for extra configuration files during development to override the standard production settings as needed. Furthermore, the framework supports overriding properties that change the configuration of your test execution by setting environment variables or simply passing Java arguments.

Because automation is supposed to run quickly, Neodymium provides support for parallel test execution and also demonstrates that setup as part of the sample test suite.

Documentation and Templates

Does Neodymium address some of your test automation challenges? Does it sound like a good entry point for your test automation?

Neodymium is hosted on GitHub (https://github.com/Xceptance/neodymium-library), where the accompanying project wiki (https://github.com/Xceptance/neodymium-library/wiki) provides extensive documentation to help you get started and answer your questions.

You might also want to take a look at the comprehensive example projects using Neodymium with Cucumber (https://github.com/Xceptance/neodymium-cucumber-example) or plain Java (https://github.com/Xceptance/neodymium-example). We’ve even provided a template project (https://github.com/Xceptance/neodymium-template) to get you started automating in no time.

License

Neodymium is licensed under the MIT License.

Who Are We

We are Xceptance. A software testing company with strong commerce knowledge and projects with customers from all around the world. Besides Neodymium, we have developed Xceptance Load Test (XLT), a load and performance test tool that is available free of charge and features an extensive range of awesome features to make the tester’s and developer’s life easier.

If you are looking for test automation that also covers the performance side of life, take a look at XLT. You can write and run load tests with real browsers including access to data from the Web Performance Timing API. In case browsers are too heavy, XLT has other modes of load testing to offer as well.

We offer professional support for Neodymium as well as implementation and training services.

XLT 4.12.1 Release

Xceptance has released version 4.12.1 of its load testing and test automation product Xceptance LoadTest.

Test Framework

  • Fix: Our timer recorder extensions for Chrome and Firefox did sometimes report invalid request entries that could not be processed by the report generator. This could happen for requests that did not complete.
  • Fix: If a test case deliberately caught an exception / assertion error and afterwards ran to completion successfully, it might nevertheless be marked as failed in the load test report.
  • Improvement: Selenium has been updated to the latest version 3.141.59 and HtmlUnitDriver to version 2.33.3.

Load Testing

  • Improvement: The new AWS data center in Stockholm, Sweden (eu-north-1) is fully supported by ec2_admin now.

Make sure to read the full online release notes.

As always, this upgrade is free and don’t forget, XLT itself is free as well. You don’t have an excuse to skip performance testing or rely on lame simple test cases anymore.

XLT 4.11 was released

Xceptance released version 4.11 of its load testing and test automation product Xceptance LoadTest. This is a feature release. We recommend upgrading to this newest version.

Here is a selection of the most important changes:

  • HtmlUnit and Selenium have been updated
  • You can run a test case with only a single data set at development time
  • XLT picks a data set automatically when a test with multiple data sets is part of a load test
  • There is a new command-line tool to automatically evaluate a test report based on your defined success criteria
  • The XLT Jenkins plugin returns a result object now with all the details when used in a pipeline
  • The XLT Jenkins plugin can now create a comparison report

See our release notes for more details. As always, this upgrade is free and don’t forget, XLT itself is free as well. You don’t have an excuse to skip performance testing or rely on lame simple test cases anymore.

Firefox 57 Changes and XLT

Firefox 57 is going to deliver a fundamental change that will affect XLT Script Developer.

As you might know, Mozilla decided to completely remove the support for XUL/XPCOM-based extensions (aka legacy extensions) in favor of extensions built upon the WebExtension API. This cut will take place on November 14, 2017, with the release of Firefox 57. Additionally, Mozilla will refuse to sign updates of legacy extensions at some point in the near future, although the exact date is not determined yet. See the Mozilla Add-ons Blog for an up-to-date timeline.

The consequence of this breaking change is that XLT Script Developer cannot be installed in Firefox 57 and higher. Also, an already installed XLT Script Developer cannot be used any longer.

We at Xceptance have been aware of this development. Over the course of the last year we have been busy evaluating several alternative options. As you might recall, we also conducted a survey back in the spring to collect your feedback.

Based on our findings and your input and after long discussions, we came to the conclusion that the feature set and comfort that had been offered by XLT Script Developer and its way of writing web automation cannot be recreated using the alternative Firefox APIs.

Therefore, we regret to announce that Script Developer is discontinued. Consequently, we don’t recommend starting new test projects based on Script Developer and XML script test cases. To be able to continue to use the features of XLT and the advantages it offers, we suggest you use XLT’s Java-based API.

If you are able to use Firefox 56 or Firefox 52/ESR, maybe in parallel to an updated version of Firefox, you can continue to work with XLT Script Developer as well as execute all your test cases as you have been.

We are aware that this decision might disappoint many of you and may leave open questions. For more information on what shaped this decision and what your options are for maintaining your existing XML script test suites in the future or migrating them to another base, please see the Q&A section below.

Q&A

Why did Mozilla decide to abandon legacy extensions?

By design, legacy extensions have not only full access to your local file system but also to the entire browser and thus to all the pages you visit. This has been causing privacy and security issues and hence Mozilla decided to abandon the API to address these problems.

Why isn’t XLT Script Developer being ported to the WebExtension API?

The possibilities offered by the WebExtension API are very limited. One such limitation, and the most important one, is that access to the local file system involves a user interaction for each and every file to save or read. This would make Script Developer simply impossible to use.

Further restrictions apply. Most of them are related to accessing and manipulating session and browsing data such as cookies or cache. In the end, Script Developer would only be able to support a very reduced feature set.

And last but not least, the outcome of our customer survey revealed needs which cannot be met by such a modest visual, non-programming approach to writing tests. See the next question for more details on the feedback we received.

Why won’t XLT Script Developer be ported to another platform?

The outcome of our survey was that users wanted a tighter integration with Java/IDEs, more commands, more ways to customize things, better flow control, and more flexibility with test data. At the end of the day, this is a full programming approach and turning the XLT Script Developer into another programming environment couldn’t address all these points.

We also believe that the concept of XML script test cases with their limited capabilities are no longer appropriate for modern testing needs. Therefore we have decided to give it up in favor of the opportunities a real programming language provides.

Can I continue to use XLT Script Developer with Firefox 56?

Yes, but at your own risk. Remember that your browser cannot be updated and therefore will not receive any security fixes. Furthermore, it may not be possible to install any Script Developer updates as this Firefox version accepts signed extensions only. And Mozilla might stop signing legacy extensions any day. See below for a better solution.

Can I continue to use XLT Script Developer with Firefox 52/ESR?

Yes, absolutely. That is the recommended way to go, at least for the next months. First, Firefox 52/ESR (Extended Service Release) will be updated with security fixes until May 2018. If you continue to use Script Developer after that date, though, you do so at your own risk. Make sure that you use this browser version for scripting only.

Furthermore, Firefox 52/ESR can be tweaked to install legacy extensions even if they are not signed by Mozilla. This way, you are still able to install Script Developer updates in case Xceptance provides some in the future.

Will the XLT framework still be able to replay XML script test cases?

Yes, XLT will continue to interpret and execute your existing XML script test cases as JUnit tests via their wrapper classes.

How to migrate existing projects?

Export all your existing XML script test cases to Java (Scripting API). From this point, you maintain your test cases in your favorite Java IDE instead of the XLT Script Developer. Since the concepts and commands are the same as in Script Developer, you will be on top of things quickly.

Instead of running your XML test cases in Script Developer, you would now run your Java-based tests as JUnit tests using your preferred WebDriver either from your IDE or using a continuous integration system.

Since your code base is plain Java now, you are free to add all the things that you might have missed in the past.

Note that XLT 4.10.0 will ship with some enhancements for Java-based test cases. For instance, Script Developer will provide an alternative export template that produces more compact code. Additionally, writing test cases directly in Java will be more comfortable as well. Stay tuned for the upcoming release and find all the details in the release notes.

Make sure you subscribe to our low-volume XLT release and news mailing list.

How long will you release XLT Script Developer updates?

TBD. Future updates of Script Developer will be bug-fix releases only (shipped as unsigned extensions once Mozilla stops signing legacy extensions). Don’t expect any new features.

Are there any other options?

Yes. There are forks of Firefox that promise to continue supporting legacy extensions while being kept up-to-date at the same time. For instance, Script Developer installs and runs nicely in Waterfox. However, we cannot predict how long this will actually work.

XLT 4.9 has been released

Xceptance released version 4.9 of its load testing and test automation product Xceptance LoadTest. This is primarily a 3rd party update release, but also delivers some improvements.

Here is a selection of the most important changes:

  • Script Developer supports Firefox 53
  • Selenium updated to version 3.4.0
  • Better reporting of JavaScript errors in script test cases
  • Master controller displays the configured load profile
  • Load test reports can be created for a subset of agents
  • Load test reports shows the number of entries in data tables and shows summary values when filtering the table
  • Demo app server ports can be reconfigured easily

Script Developer

Script Developer has been made compatible with the latest available Firefox version, while outdated versions are not supported any longer. Script Developer runs on Firefox 45/ESR up to 53 now.

Update Instructions: Firefox will not auto-update older versions of Script Developer to 4.9.0. You will need to do this manually. Please remove the currently installed version first and afterwards install the new version by simply dragging and dropping the file xlt-scriptdeveloper-4.9.0.xpi onto Firefox. Auto-updating within the 4.9.x product line will then work as usual again.

Alternatively you can visit the Mozilla Add-On marketplace and install Script Developer from there (https://addons.mozilla.org/en-US/firefox/addon/xceptance-script-developer/). Please make sure you uninstall your locally installed version first.

Framework

XLT now ships with Selenium 3.4.0. Make sure you update your locally installed driver binaries to the latest available version. This is especially true for geckodriver. In case you experience issues with geckodriver / Firefox, you might be better off running FirefoxDriver in legacy mode. The legacy mode is more mature.

All other core libraries have been updated as well. This also includes HtmlUnit for an improved browser emulation.

The XLT framework also comes with some functional improvements. In case a JavaScript expression in your script test case could not be evaluated successfully for any reason, the root cause will now be listed as part of the exception message. Libraries that make use of Java’s built-in logging framework do no longer log to the console, but to XLT’s log file.

Load and Performance Testing

The Mastercontroller now prints the configured load profile to the console when starting a load test and also when displaying the current status. This helps to spot test configuration mistakes earlier. Intermediate results downloaded, while a load test is still running, will now be flagged to distinguish them from final results.

The load test report shows the number of entries in a data table, and when filtering a data table, the footer row is updated accordingly. Load test reports may also be created for only a subset of the agents. You might remember that version 4.8 already delivered the ability to render reports for specific test cases only.

Last but not least, ec2_admin prints more details about running AWS machine instances and lets you review your choice before actually terminating running instances.

Demo App Server / Posters Store

The app server that hosts our demo applications uses ports 8080 and 8443 by default. Since these ports are often already used by other applications, you can now reconfigure them easily.

Our demo application Posters Store now runs with HTTPS only. Any HTTP request will be redirected to use HTTPS.

Sounds interesting? More details can be found in the release notes of XLT 4.9.

Release of XLT 4.8

XLT 4.8 is primarily a technology update release, but also comes with some new features.

First and foremost, XLT now ships with Selenium 3, the new version of the WebDriver library. All other core libraries have been updated as well. This also includes HtmlUnit for an improved browser emulation. Beginning with this release, XLT requires Java 8 to run.

The XLT framework also comes with some functional improvements. XLT now supports OperaDriver out of the box and can run FirefoxDriver in either the new Marionette mode using geckodriver or in the “old” legacy mode. When you drive Firefox via XltFirefoxDriver, you will get a much more detailed result browser now, with almost the same request and response details that you already know from XltDriver. Any values that you programmatically add to the newly introduced value log of a session are shown in the result browser as well. Furthermore, most of the XLT framework properties can now be configured not only globally, but also specifically for a certain test scenario.

For load testers, there is something in the box as well. If you use the AWS EC2 cloud a lot, you will be glad to hear that the new AWS data center in Ohio is now fully supported. The load test report has been tuned to become usable much faster, even with lengthy pages such as the Requests page.

Last but not least, the Poster Store demo application and the XLT Jenkins Plug-In have both been updated. If you ever wanted to load-test your WebDAV server, there is now a new demo test suite for that.

Sounds interesting? More details can be found in the release notes of XLT 4.8.

Release of XLT 4.7

Summary

Xceptance released version 4.7 of its load testing and test automation product Xceptance LoadTest. It features a wide range of improvements and new functionalities.

Here is a selection of the most important changes.

  • Script Developer fully supports test data sets now
  • Script Developer learned “post steps” for easy cleanup or tear down of test cases
  • Script Developer and the framework support the new echo command for enhanced debugging
  • Load testing supports a variable load factor function to easily and globally vary load quickly
  • Load test reports display DNS resolution time
  • Load test reports display error charts per error type and response code
  • Data tables and charts for custom values display more details
  • Data tables have sticky headers for easier data evaluation
  • Load test reports can be created for specific test scenarios by filtering to include or exclude specific scenarios during report creation
  • XLT can log method and POST data to its timer files
  • All core libraries have been updated for improved browser support and improved performance
  • The new Amazon data center in Mumbai, India (ap-south-1) has been added

See below for more details of the highlights. Make sure to read the full online release notes.

As always, this upgrade is free for everyone.

Continue reading Release of XLT 4.7

Localisation Verifier – A Custom Java Module for Script Developer

Introduction

When employing XLT Script Developer you usually resort to automated or manual scripting to drive your testing. Sometimes though you will face a very specific or complex task that can not be expressed that easy with the standard scripting capabilities of Script Developer. For these types of scenarios Script Developer provides the option to integrate a custom Java module. With custom modules you have the full power of your Java runtime and are able to achieve virtually any testing objective.

The following blog post will describe a small custom Java module we created and used recently. By this example we will explain when to choose this route and demonstrate the creation and execution of Java modules. Ultimately you will be able to add Script Developer’s custom module option to your testing arsenal.
Continue reading Localisation Verifier – A Custom Java Module for Script Developer

Multi-Browser Support for Test Automation with XLT

Summary

In today’s post we will discuss the steps necessary to enhance an XLT-based test suite with multi-browser support. We will show how to tag your test cases to conveniently run them in different environments and execute the test suite in a local or remote fashion.

Introduction

Xceptance maintains a MIT licensed test suite at GitHub which demonstrates functional testing for large scale projects. With the suite we’ve put an emphasis on clear structures, naming and test case organization. Targeting Demandware’s SiteGenesis storefront at heart, the underlying concepts and mechanisms are valuable for everyone building test suites for comparable web applications with XLT. Next to being a template for test automation and best practices in test suite design, it can be a starting point ready to pick up in your very own projects. We regularly utilize it and want to encourage you to explore, employ and contribute.

A regular challenge in testing ecommerce applications is the variety of different browsers and platforms that are available today. As you probably know XLT, the test automation and load testing framework from Xceptance, is based on Selenium browser automation and the Webdriver API. Supporting multiple browsers therefore comes naturally. This blog post will demonstrate how XLT is able to streamline different testing environments directly in your test suite. You will learn how to execute your tests locally and remotely with the help of Sauce Labs and similar automated testing platforms. Along the way you will pick up some details about XLT as well as Script Developer and quickly find yourself equipped with a ready to use multi-browser test suite example.
Continue reading Multi-Browser Support for Test Automation with XLT