Closed Bug 1101799 Opened 10 years ago Closed 9 years ago

add a command to return the server's currently supported API

Categories

(Remote Protocol :: Marionette, defect)

x86
All
defect
Not set
normal

Tracking

(Not tracked)

RESOLVED INCOMPLETE

People

(Reporter: mdas, Unassigned)

Details

It would be useful if we could ask marionette server to return us a structure that tells us what functions it currently supports. This would allow us to dynamically generate a client for it on the fly, instead of manually updating the functions.

TaskCluster does this currently where you can ask it for its currently supported API https://raw.githubusercontent.com/taskcluster/taskcluster-client/master/lib/apis.js where you get returned a json blob
I am not sure I understand the request. The API it supports is for browser automation and we are going to be augmenting it constantly.

We already return session data when you create a new session into marionette. see http://dxr.mozilla.org/mozilla-central/source/testing/marionette/marionette-server.js#159
Flags: needinfo?(mdas)
The idea would be to send a message to the server (without having to start a session), and it will return to me a json blob of all the commands it supports. So I could connect to localhost:2828, and send a command like 'listAPI', and it will return something like:

{ "newSession": {"required": {}, "optional": { "sessionID": "string"}, "description": "This starts a new session"},
  "getTitle": {"required": {}, "optional": {}, "description": "Gets the title of the current frame"},
  ... for each command...
}

The above is a hand-wavy structure, but the idea is we return enough information from this call so that the caller of listAPI can consume all this data and autogenerate a client *tailored* for the server.

Some use cases:
* I'm using some older version of Firefox or FxOS and I want to use marionette. I don't know which client to use. The autogenerator can generate one for me without me running around trying to match this version of firefox to a branch, and then getting the appropriate client.
* For Bug 1101791, I'd ideally be adding more methods to the server via an extension, so the local end can then ask the server what api it currently implements, and it can tailor a client for it
Flags: needinfo?(mdas)
The traditional approach to this problem has been to check for what capabilities the returned session supports.  If they contain the takesScreenshot but not the takesElementScreenshot capability it's safe to assume you can use Marionette.take_screenshot() but not HTMLElement.take_screenshot().

This is called a role-based interface approach through which the Marionette interface can be augmented with new functionality based on what it supports.  Whether we do that currently I don't know.

On the other hand, if the goal is to generate a new client at runtime I'm sceptical of the benefits.  Disregarding a few breaking changes we need to make to reach WebDriver spec level compatibility, the changes to the input and output of Marionette functions will rarely, if ever, change.

There are also a few inherent problems in auto-generating APIs.

1. Difficult to debug problems because it's not obvious at runtime what the input and output is.

2. Generated APIs are often not idiomatic to the language.  It's not a requirement that the local-end APIs follow or match the remote's.

3. An API is often a one-off thing.  The fact that ours changes is because we're implementing a moving target specification which often have larger breaking changes than the function name, argument name and type, and return value of a particular command.
Status: NEW → RESOLVED
Closed: 9 years ago
Resolution: --- → INCOMPLETE
we return a capability that solves this
Product: Testing → Remote Protocol
You need to log in before you can comment on or make changes to this bug.