Comments on WebDriver "W3C Editor's Draft 22 August 2012"

I've just completed a read of the WebDriver "W3C Editor's Draft 22 August 2012", and as someone who hasn't been privy to any of the spec discussions, but who knows a lot about Selenium RC, a thing or two about WebDriver, and has been through the standardization process before, I thought a few comments might be helpful.  I apologize for the terseness of some of these - they were typed while reading, and aren't meant to insult.

Ross Patterson

Section
Comment

1.3
"User" in this context means a program ivoking the API, not a human being.

Is it intended that independent implementations of the "local" and "remote" sides of the API should be able to interoperate?  That doesn't appear to be a requirement, but it seems like an obvious good idea.
2
"user-facing" -> "local"

"between the browser being automated and the user of the API" -> "between the local and remote sides of the API"

"How these are encoded and transmitted ...  is left undefined" means that local and remote sides cannot interoperate.
2.1
The WebIDL notation is used in this section, but not in others.  It isn't at all clear why other sections (e.g., 4.1.1) codify values without reference it WebIDL.
2.4
The missing codes (e.g., 1-6) are presumably obsolete from prior work, and should be marked as reserved and obsolete.
3.1.2
has() is overloaded with get() semantics, and should not be.  How is a caller supposed to know the difference between has(falseBooleanCapability) and has(unsetBooleanCapability)?
4.1
sessionId is described as a string in 2.1 and 2.2, but a UUID in this section.  One or the other must be wrong.  I suggest 2.1 and 2.2 are correct, and that the sessionId be treated as an opaque string of unspecified form and size.
2.
"sessionId fields" -> "sessionId field"
4.
What is the correct response if there are conflicts between capabilities?
6.
What does "the parts of this specification" mean?  Is it a combination of the desiredCapabilities and requiredCapabilities?

Does "There is no requirement for the local end to validate that ..." mean that the remote end commits that they match?
4.1.1
Is there are recommended or required convention for platform names that are not standardized (e.g., a la CSS vendor prefixes)?
4.1.2
It is not possible for a "Timeout" status to be returned in the case of an infinite time limit.

For "unknownError", the "value" should be a string (as in Timeout).
5.1
normal
"remote ends" -> "remote end"
5.2
"browser under test" -> "browser"

"returning control to the user" (et al.) -> "responding to the command"

"META tags" -> "META tag"

"user credentials are requested by the browser" -> "an HTTP request returns a 401 response"?
5.2.1
Why is this here instead of in section 4.1.1?
5.3
"WebDriver instance" is not a defined term.

Does this mean a remote end should return failure if a local end sends it a command when the browser is "busy"?
6.1
Perhaps the W3C DOM standards would have better a definition for "window"?
6.2
Does "unique to the window" mean globally and temporally unique, unique within the set of windows for this session, or something else?

Is the UUID suggestion informative or normative?

"Return Value" should describe the value, not just its type.  For example, "Return Value: windowHandle {string}"
6.3
Does the "... at the time of collecting the window handles the javascript expression ..." mean that at the time of response, some might now be closed?

Why the restrictive SHOULD on ordering?  Surely that will encourage API users to act as if it were a MUST, and then find cases where it is not true by trial and error.
6.5
The width and height units should be specified.  Are they implied to be pixels?
7.2
There should be separate, mutually exclusive parameters for windowHandle, windowName, and windowId.  It should not be necessary for a remote end to determine which the local end meant to specify, because one type of value can easily be mis-interpreted as another.

"default content" is not a defined term.
7.3
There should be separate, mutually exclusive parameters for frameIndex, frameName, and frameId.  It should not be necessary for a remote end to determine which the local end meant to specify, because one type of value can easily be mis-interpreted as another.
9
Does "The IDs used to refer to different underlying DOM Elements must be unique." mean globally and temporally unique, unique within the set of elements for this session, or something else?
9.3.1
Does this imply a strategy named "ARIA"?
9.3.2
Shouldn't this be a strategy, not a capability?

What is the strategy name?
9.3.3
The link is recursive.

What is the strategy name?
9.3.4
What is the strategy name?
9.3.5
Specify the expected results, not the implementation technique.

What is the strategy name?
9.3.6
Specify the expected results, not the implementation technique.

What is the strategy name?
9.3.7
Do not specify the implementation technique.
10.1
Selenium WebDriver also requires that the element be visible in the browser window.  This section does not contain a similar requirement.  Is that an intentional difference?
10.2
"WebDriver determines ..." -> "The remote end determines ...".

There is no "getProperty" method described in the document.

Specify the expected results, not the implementation technique.
10.4
Remove "such as Lynx" - defining behavior in terms of a specific browser is bad practice in a standard.

"...  depth-first to step 1 with ..." - there are two "1" steps, which one?

Wouldn't it be simpler to reference the XPath normalize-space() function instead of detailing this algorithm?
13.
Are fractional milliseconds allowed, or is "ms" an integer?
14.3.2.1
The algorithm definition appears to be non-normative, and should probably be moved to an appendix.

Is there a reference for the Unicode PUA usage? If so, it should be cited.