WebDriver API improvements

[jason0x43]

The goal of this ticket is to propose improvements to Intern's WebDriver API. What changes, if any, would make the WebDriver API easier to use in Intern 5?

Several improvements that have been suggested:

• Add locator helper #1039 would give Intern a more flexibly way to specify and use locators throughout the rest of the API
• Consider allowing method chaining on Element object #1032 would allow method chaining on Elements as well as commands
• Improving typings for webdriver helpers #1024 would simplify the process creating webdriver helper functions

[jason0x43]

#1045 suggests that switchToFrame should support string frame identifers (names or IDs), similarly to how window.frames behaves. How closely should Intern try to stick to webdriver semantics? Would using a string identifier be a worthwhile simplification, or should we more clearly document that switchToFrame should only take a number or element?

That last bit is complicated by the fact that we may still need to support the JsonWireProtocol for a bit, and JWP's frame handler accepts string IDs for frames.

[jason0x43]

A question to be answered: given that Intern 5's supported browser range will likely be IE11 and the last few versions of the other major browsers (Safari, FF, Chromium Edge, Chrome), do we need a lot of JWP support, or have the drivers mostly switched to W3C mode?

[jason0x43]

We should defer feature testing until commands are actually called. Currently, the pattern is to run a bunch of tests when setting up the session, then use those flags in session commands. This can significantly extend startup time, and runs many tests that will likely not be needed.

Instead, Intern should generally defer testing until commands are actually called the first time. The pattern should be

command() {
  if (this.capabilities.commandIsBroken) {
    return this.execute('fallback logic');
  } else {
    return this.serverPost('/command').catch(error => {
      if (/* error is a command failure */) {
        this.capabilities.commandIsBroken = true;
        return this.command();
      } else {
        throw error;
      }
    });
  }
}

There are some cases in which this won't work -- calling certain unsupported commands can crash some clients. In those cases, feature flags should be pre-set as they are now.

[jason0x43]

Some potential webdriver-related tasks:

Support the W3C webdriver spec

Intern supports pieces of this spec, but not everything. In particular, some of the newer parts of the spec, like the Actions API, are entirely unsupported.

Default to W3C webdriver

At this point most webdrivers have made the switch to W3C webdriver, at least partially. Intern should start assuming W3C by default. For this to handle everything the JWP code does, though, we'll need more complete W3C support.

JWP can do somethings that W3C webdriver cannot, like indicate whether an element is displayed. Intern should test for available JWP features when it needs certain functionality, and fall back to JS implementations (or just error for certain commands) when no such features are available.

The specific task here will be mostly be to adjust Intern's internal semantics. Intern should assume that every endpoint uses W3C semantics, and feature tests and capability flags should reflect that. W3C endpoints should be called by default.

Support a standard Promise-based API

Intern's webdriver API is currently based around a chaining pattern for Commands. That works well in many cases, although it can be confusing to users and requires hacks such as end(). There is also inconsistency between Command methods, which return Commands, and Element methods, which return Promises.

Intern's primary webdriver API should be based around standard promises. This will simplify the internal code and allow the API to be used with async/await, which can significantly simplify test code. It will also improve consistency between the Command and Element APIs.

We may also want to temporarily maintain a chainable Command API, just to ease the transition. If we're particularly ambitous we could try creating a converter to automatically port Command chains to async/await.

Add support for webdriver alternatives

This one is a bit lower priority, but it may be worthwhile to provide adapters for Puppeteer and PlayWright (and similar projects) to allow them to be used through Intern's webdriver API. This would be different than one of Intern's tunnel; a tunnel lets Intern access something that provides the standard WebDriver API over a network connection, whereas this would allow Intern to use a library that provided a different API.

Defer feature tests

Feature tests should be deferred by default until a function is initially used. This will eliminate the initial feature tests which, while useful, are perceived as an annoyance by many users.

Certain features cannot be tested as they will crash browsers; these should continue to be hardcoded.

Externalize default features

A low priority update would be to move features that are currently set manually to JSON files. This will simplify the code and make it easier to see which features are being applied for a given browser.

Support DOM-like semantics for some commands

Intern's webdriver API is intended to make webdriver convenient to use. It doesn't necessarily need to mirror webdriver commands or their semantics, and there are places where Intern could make webdriver simpler or more intuitive. One case are commands like switchToFrame. The webdriver endpoint accepts only numbers or webdriver element IDs. However, users may expect to be able to specify frames using names or CSS selectors as they would in browser-based JS code.

An alternative, at least in this specific case, would be to output a more meaningful error. If the user provides a string and the call to the webdriver endpoint fails with an InvalidArgument error, Intern knows enough to be able to suggest to the user that the problem may be an invalid ID format.

[aciccarello]

Support a standard Promise-based API

Intern's webdriver API is currently based around a chaining pattern for Commands. That works well in many cases, although it can be confusing to users and requires hacks such as end(). There is also inconsistency between Command methods, which return Commands, and Element methods, which return Promises.

I wonder if async/await support could be added by making the interface then-able rather than a full promise. It might complicate the implementation if you need to wait for the end of the chain to trigger an action. This blog post has some interesting thoughts on the pattern.