From 48f8a03528278f3e293db69a99ee933859aa47ab Mon Sep 17 00:00:00 2001 From: AutomatedTester Date: Wed, 29 Apr 2015 23:48:39 +0100 Subject: [PATCH] reword new Session to be more precise --- 04_sessions.html | 130 +++++++++++++++++------------------------- webdriver-spec.html | 134 +++++++++++++++++--------------------------- 2 files changed, 100 insertions(+), 164 deletions(-) diff --git a/04_sessions.html b/04_sessions.html index 481b263ba..e80eb62ab 100644 --- a/04_sessions.html +++ b/04_sessions.html @@ -96,7 +96,7 @@

Sessions

requires passing a session ID.
-

newSession()

+

New Session

@@ -109,89 +109,60 @@

newSession()

HTTP Method
-

The process for successfully creating a session MUST be:

+

The remote end steps for the New Session command are:

+
    -
  1. The local end creates a new Capabilities instance describing the desired capabilities - for the session. The Capabilities object MUST be defined but MAY be empty.
    2. -
  2. The local end MUST populate parameters with an object containing an - entry named "desiredCapabilities" with the value set to the Capabilities instance from the previous step. An optional - "requiredCapabilities" entry MAY also be created and populated with a Capabilities instance. The "sessionId" fields - SHOULD be left empty.
    3. -
  3. The remote end MUST examine the "requiredCapabilities" parameter if specified, SHOULD examine the "desiredCapabilities" parameter, and MUST create a new session matching as many of the Capabilities as - possible. - How the new session is created depends on the implementation of this specification. -
      -
    • If any of the "requiredCapabilities" cannot be fulfilled by the new session, the remote end MUST quit the session and return the - session not created error code. The sessionId MUST be left as the default value unless one was set in the initial request, in which case that value MUST be used. The error message SHOULD list all unmet required capabilities though only a single required capability MUST be given.
      • -
    • If a capability is listed in both the requiredCapabilities and desiredCapabilities, the value in the requiredCapabilities MUST be used.
      • +
    • +

      Let capabilities be the result of getting a property named "capabilities" + from the parameters argument.

      +
      • +
    • +

      + Let resultant capabilities be the result of calling process capabilities + with capabilities as an argument. If the result is an error, return an + error with the code session not created. +

      +

      + An Intermediary Node may inspect capabilities for items that might influence + how jobs are distributed. When the Intermediary Node has completed any checks on + capabilities it MUST forward the request on to the Remote End. +

      +
      • +
    • +

      + If the list of active sessions is not empty: +

      +

      • -
    • The session MUST be assigned a sessionId which MUST be unique for each session (a UUID SHOULD be used). Generating the sessionId - MAY occur before the session is created. If the parameters object had the "sessionId" key with a value, this MAY be - discarded in favour of the freshly generated sessionId. Because of this, it is - recommended that sessionId generation be done on the remote end. If the sessionId has already been used, a Response MUST be sent with the status - code set to session not created and the value being an explanation that the sessionId has previously been used.
      • -
    • The remote end MUST then return the session id, with the following fields MUST be set to: -
        -
      • "sessionId": the sessionId associated with this session.
        • -
      • "value": a Capabilities instance. The keys of this Capabilities instance MUST be the strings given in each of the supported Capabilities as defined in the relevant sections of this specification. Supported functionality MUST be included in this Capabilities instance, while unsupported functionality MAY be omitted.
        • -
      • "status": the success error code.
        • -
      • -
- -

As stated, when returning the value of the Response, the remote end MUST include the capability names and values of all supported Capabilities from this specification. They MAY also include any additional capability names and values of supported Capabilities implemented independently of this specification. Local ends MAY choose to ignore this additional information. Intermediate nodes between the local and remote ends MAY interpret the Capabilities being returned.

- -

If the browserName is given as a desired capability and omitted from the required capabilities, and the returned browserName value does not match the requested one, local ends SHOULD issue a warning to the user. How this warning is issued is undefined, but one implementation could be a log message. In this particular case, local ends MAY chose to change the Response's status code to session not created, and modify the value to explain the cause, including the value originally returned as the browserName capability. If this is done, the local end MUST ensure that the remote end quits the session.

- -
-

Capability Names

-

The following keys SHOULD be used in the Capabilities instances. They all default to the null string.

-
-
browserName
-
The name of the desired browser as a string.
-
browserVersion
-
The version number of the browser, given as a string.
-
platformName
-
The OS that the browser is running on, matching any of the platform names given below.
-
platformVersion
-
The version of the OS that the browser is running on as a string.
-
- -
-

Platform Names

-

The following platform names are defined and MUST be used, case sensitively, for the "platformName" unless the actual platform being used is not given in this list:

+

  • Let session id be the result of generating a UUID.

    • +

  • Append session id to list of active sessions.

    • +
  • +

    + Let data be an empty JSON Object with the following entries. +

      -
    • android
      • -
    • ios
      • -
    • linux
      • -
    • mac
      • -
    • unix
      • -
    • windows
      • +
    • +

      + sessionId: the value of session Id. +

      +
      • +
    • +

      + capabilities: the value of resultant capabilities. +

      +
    -

    In addition "any" MAY be used to indicate the underlying OS is either unknown or does not matter.

    - -

    Implementors MAY add additional platform names. Until these are standardized, these MUST follow the conventions outlined in extending the protocol section with the exception that the vendor prefix SHOULD omit the leading "-" character.

    - -

    For example, Mozilla's Firefox OS could be described as either "-MOZ-FIREFOXOS". The latter makes it easier for local ends to specify an enum of supported platforms and is therefore recommended in this case.

    - - - -
    • -
    -
    -

    Error Handling

    -

    The following status codes MUST be returned by the "newSession" command:

    -
    -
    success
    -
    The session was successfully created. The "value" field of the Response MUST contain a Capabilities object describing the session.
    -
    timeout
    -
    The new session could not be created within the time allowed for command execution on the remote end. This - time MAY be infinite (in which case this status won't be seen). The "value" field of the Response SHOULD contain a string explaining that a timeout has - occurred, but it MAY be left as the null value or filled with the empty string.
    -
    unknown error
    -
    An unhandled error of some sort has occurred. The "value" field of the Response SHOULD contain a more detailed - description of the error as a string.
    -
    + +
  • +

    Return success with data data. +

    • +

    Remote End Matching of Capabilities

    @@ -205,7 +176,6 @@

    Remote End Matching of Capabilities

    For all comparisons, if the key is missing (as determined by a call to Capability.has() returning "false"), that particular criteria shall not factor into the comparison.

    -

    Removing a Session

    diff --git a/webdriver-spec.html b/webdriver-spec.html index 2260cd2c5..84fb7e147 100644 --- a/webdriver-spec.html +++ b/webdriver-spec.html @@ -881,7 +881,7 @@

    Sessions

    requires passing a session ID.
    -

    newSession()

    +

    New Session

    @@ -894,89 +894,60 @@

    newSession()

    HTTP Method
    -

    The process for successfully creating a session MUST be:

    +

    The remote end steps for the New Session command are:

    +
      -
    1. The local end creates a new Capabilities instance describing the desired capabilities - for the session. The Capabilities object MUST be defined but MAY be empty.
      2. -
    2. The local end MUST populate parameters with an object containing an - entry named "desiredCapabilities" with the value set to the Capabilities instance from the previous step. An optional - "requiredCapabilities" entry MAY also be created and populated with a Capabilities instance. The "sessionId" fields - SHOULD be left empty.
      3. -
    3. The remote end MUST examine the "requiredCapabilities" parameter if specified, SHOULD examine the "desiredCapabilities" parameter, and MUST create a new session matching as many of the Capabilities as - possible. - How the new session is created depends on the implementation of this specification. -
        -
      • If any of the "requiredCapabilities" cannot be fulfilled by the new session, the remote end MUST quit the session and return the - session not created error code. The sessionId MUST be left as the default value unless one was set in the initial request, in which case that value MUST be used. The error message SHOULD list all unmet required capabilities though only a single required capability MUST be given.
        • -
      • If a capability is listed in both the requiredCapabilities and desiredCapabilities, the value in the requiredCapabilities MUST be used.
        • +
      • +

        Let capabilities be the result of getting a property named "capabilities" + from the parameters argument.

        +
        • +
      • +

        + Let resultant capabilities be the result of calling process capabilities + with capabilities as an argument. If the result is an error, return an + error with the code session not created. +

        +

        + An Intermediary Node may inspect capabilities for items that might influence + how jobs are distributed. When the Intermediary Node has completed any checks on + capabilities it MUST forward the request on to the Remote End. +

        +
        • +
      • +

        + If the list of active sessions is not empty: +

        +

        • -
      • The session MUST be assigned a sessionId which MUST be unique for each session (a UUID SHOULD be used). Generating the sessionId - MAY occur before the session is created. If the parameters object had the "sessionId" key with a value, this MAY be - discarded in favour of the freshly generated sessionId. Because of this, it is - recommended that sessionId generation be done on the remote end. If the sessionId has already been used, a Response MUST be sent with the status - code set to session not created and the value being an explanation that the sessionId has previously been used.
        • -
      • The remote end MUST then return the session id, with the following fields MUST be set to: -
          -
        • "sessionId": the sessionId associated with this session.
          • -
        • "value": a Capabilities instance. The keys of this Capabilities instance MUST be the strings given in each of the supported Capabilities as defined in the relevant sections of this specification. Supported functionality MUST be included in this Capabilities instance, while unsupported functionality MAY be omitted.
          • -
        • "status": the success error code.
          • -
        • -
    - -

    As stated, when returning the value of the Response, the remote end MUST include the capability names and values of all supported Capabilities from this specification. They MAY also include any additional capability names and values of supported Capabilities implemented independently of this specification. Local ends MAY choose to ignore this additional information. Intermediate nodes between the local and remote ends MAY interpret the Capabilities being returned.

    - -

    If the browserName is given as a desired capability and omitted from the required capabilities, and the returned browserName value does not match the requested one, local ends SHOULD issue a warning to the user. How this warning is issued is undefined, but one implementation could be a log message. In this particular case, local ends MAY chose to change the Response's status code to session not created, and modify the value to explain the cause, including the value originally returned as the browserName capability. If this is done, the local end MUST ensure that the remote end quits the session.

    - -
    -

    Capability Names

    -

    The following keys SHOULD be used in the Capabilities instances. They all default to the null string.

    -
    -
    browserName
    -
    The name of the desired browser as a string.
    -
    browserVersion
    -
    The version number of the browser, given as a string.
    -
    platformName
    -
    The OS that the browser is running on, matching any of the platform names given below.
    -
    platformVersion
    -
    The version of the OS that the browser is running on as a string.
    -
    - -
    -

    Platform Names

    -

    The following platform names are defined and MUST be used, case sensitively, for the "platformName" unless the actual platform being used is not given in this list:

    +

  • Let session id be the result of generating a UUID.

    • +

  • Append session id to list of active sessions.

    • +
  • +

    + Let data be an empty JSON Object with the following entries. +

      -
    • android
      • -
    • ios
      • -
    • linux
      • -
    • mac
      • -
    • unix
      • -
    • windows
      • +
    • +

      + sessionId: the value of session Id. +

      +
      • +
    • +

      + capabilities: the value of resultant capabilities. +

      +
    -

    In addition "any" MAY be used to indicate the underlying OS is either unknown or does not matter.

    - -

    Implementors MAY add additional platform names. Until these are standardized, these MUST follow the conventions outlined in extending the protocol section with the exception that the vendor prefix SHOULD omit the leading "-" character.

    - -

    For example, Mozilla's Firefox OS could be described as either "-MOZ-FIREFOXOS". The latter makes it easier for local ends to specify an enum of supported platforms and is therefore recommended in this case.

    - - - -
    • -
    -
    -

    Error Handling

    -

    The following status codes MUST be returned by the "newSession" command:

    -
    -
    success
    -
    The session was successfully created. The "value" field of the Response MUST contain a Capabilities object describing the session.
    -
    timeout
    -
    The new session could not be created within the time allowed for command execution on the remote end. This - time MAY be infinite (in which case this status won't be seen). The "value" field of the Response SHOULD contain a string explaining that a timeout has - occurred, but it MAY be left as the null value or filled with the empty string.
    -
    unknown error
    -
    An unhandled error of some sort has occurred. The "value" field of the Response SHOULD contain a more detailed - description of the error as a string.
    -
    + +
  • +

    Return success with data data. +

    • +

    Remote End Matching of Capabilities

    @@ -990,7 +961,6 @@

    Remote End Matching of Capabilities

    For all comparisons, if the key is missing (as determined by a call to Capability.has() returning "false"), that particular criteria shall not factor into the comparison.

    -

    Removing a Session

    @@ -3779,10 +3749,6 @@

    Capabilities

    Capabilities are used by WebDriver implementations to enumerate the parts of this specification that they support. They are also used when establishing a new session to descrive the required or desired capabilities. This appendix collects the capabilities mentioned in this spec into one place.