AngularJS and WebDriver bits and pieces for Java (port of Protractor)
Java JavaScript HTML Other
Clone or download
Latest commit 198e61b Jun 26, 2018


A small library of WebDriver locators and more for AngularJS (v1.x) and Angular (v2.x +), for Java.


We have taken JavaScript from Angular's Protractor project. While ngWebDriver perfectly compliments the Java version of WebDriver, it has to pass JavaScript up to the browser to interoperate with Angular, and the Protractor project has done the hard work (including testing) to make that solid. This project benefits from that work.

You can use ngWebDriver today with the regular Java Selenium2/WebDriver libraries. You can also use it with FluentSelenium for extra terseness.


Like Protractor, ngWebDriver works with Angular versions greater than 1.0.6/1.1.4, and is compatible with Angular 2 applications. Note that for Angular 2 apps, the binding and model locators are not supported. We recommend using by.css.


Waiting for Angular to finish async activity

ChromeDriver driver = new ChromeDriver();
NgWebDriver ngWebDriver = new NgWebDriver(driver);

Do this if WebDriver can possibly run ahead of Angular's ability finish it's MVC stuff in your application.



As Protractor's repeater locator this works for arbitrary ng-repeat elements, not just <tr> or <td>.

ByAngular.repeater("foo in f")
ByAngular.repeater("foo in f").row(17)
ByAngular.repeater("foo in f").row(17).column("")
ByAngular.repeater("foo in f").column("")


As Protractor's exactRepeater

ByAngular.exactRepeater("foo in foos")
ByAngular.exactRepeater("foo in foos").row(17)
ByAngular.exactRepeater("foo in foos").row(17).column("")
ByAngular.exactRepeater("foo in foos").column("")


As Protractor's binding locator

// You can also use a substring for a partial match


As Protractor's exactBinding locator



As Protractor's model locator



As Protractor's options locator

ByAngular.options("c for c in colors")


As Protractor's buttonText locator

ByAngular.buttonText("cLiCk mE")


As Protractor's partialButtonText locator

// If you have a button name "Click me to open", using just "click" would do if you partialButtonText
ByAngular.partialButtonText("cLiCk ")


As Protractor's cssContainingText locator

ByAngular.cssContainingText("#animals ul .pet", "dog")

Angular model interop

As with Protractor, you can change items in an Angular model, or retrieve them regardless of whether they appear in the UI or not.

Changing model variables

NgWebDriver ngWebDriver = new NgWebDriver(driver);
// change something via the model defined in $scope
ngWebDriver.mutate(formElement, "", "'Wilma'");
// Note Wilma wrapped in single-quotes as it has to be a valid JavaScript
// string literal when it arrives browser-side for execution

Getting model variables

As a JSON string:

NgWebDriver ngWebDriver = new NgWebDriver(driver);
// Get something via the model defined in $scope
String personJson = ngWebDriver.retrieveJson(formElement, "person");

As a string:

NgWebDriver ngWebDriver = new NgWebDriver(driver);
// Get something via the model defined in $scope
String personName = ngWebDriver.retrieveAsString(formElement, "");

As a number:

NgWebDriver ngWebDriver = new NgWebDriver(driver);
// Get something via the model defined in $scope
Long personAge = ngWebDriver.retrieveAsLong(formElement, "person.age");

As Map/dict:

NgWebDriver ngWebDriver = new NgWebDriver(driver);
// Get something via the model defined in $scope
Map person = (Map) ngWebDriver.retrieve(formElement, "person");
// note - could be List instead of a Map - WebDriver makes a late decision on that

Helping NgWebDriver find Angular apps in a page

Getting "Cannot read property '$$testability' of undefined" ?

If you're seeing $$testability referenced in a WebDriver error, then work out in you have correctly set selector for the "root element" on the Angular app. Specifically have you used .withRootSelector(..) in situations where you need to use it? Details about how to recover from that here...

To specify a different "root selector" to help ngWebDriver find the Angular app, take a look at what is defined in the ng-app attribute in the page in question. Examples:

NgWebDriver ngwd = new NgWebDriver(webDriver).withRootSelector("something-custom");
ByAngular.Factory baf = ngwd.makeByAngularFactory()
WebElement element = webDriver.findElement(baf.exactRepeater("day in days"));;

// locators
ByAngular.withRootSelector("something-custom").exactRepeater("day in days");

// or
ByAngular.Factory baf = ByAngular.withRootSelector("something-custom");
ByAngularRepeater foo = baf.exactRepeater("day in days");

Alternate selectors

Referring to a handy StackOverflow questions - No injector found for element argument to getTestability, you can use the applicable selector for your Angular app:

  • '[ng-app]'- matching an element that has the arribute ng-app (this is the default)
  • '#my-app' - matching an id my-app
  • '[fooBar]' - matching an attribute fooBar on any element
  • '[module=todoApp]' - the "todo app" module (amongst others) on the home page.

There's a reference to css selectors you'll need to read - - because that's the type of string it is going to require.

Still needing help on $$testability ?

Read the five or so bug reports on $$testability and how (most likely) you have to learn a little about you application so that you can use .withRootSelector("abc123"). Those bug reports: Also deeply read the css_selectors page on (link above) so you can fine tune your selector fu before filing a bug against this project.

Other Functions


Returns the URL of the page.

String absoluteUrl = new NgWebDriver(driver).getLocationAbsUrl();

Code Examples

All our usage examples are in a single test class:

Including it in your project



<!-- you still need to have a dependency for preferred version of
  Selenium/WebDriver. That should be 3.3.1 or above -->


Download from Mavens Central Repo


Last Release: 1.1.4 - Jun 21, 2018


Seeking help

  1. take a look all of this README - it is not that long
  2. take a look at the issues (open and closed)
  3. read the Code of Conduct and raise an issue, but be sure to make it really really easy for committers to reproduce your error. Like a clone and a build and - bang - perfect reproduction.
  4. if there's some reason you can't do the reproduction on GitHub contact Paul Hammant - - for custom support.