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

Thanks for the feedback! This is great.

Simon


On Wed, Aug 22, 2012 at 5:28 PM, Ross Patterson <rpatterson@parature.com>wrote:

> 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.
> ****
>