lib/atoms/response.js

1// Licensed to the Software Freedom Conservancy (SFC) under one
2// or more contributor license agreements. See the NOTICE file
3// distributed with this work for additional information
4// regarding copyright ownership. The SFC licenses this file
5// to you under the Apache License, Version 2.0 (the
6// "License"); you may not use this file except in compliance
7// with the License. You may obtain a copy of the License at
8//
9// http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing,
12// software distributed under the License is distributed on an
13// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14// KIND, either express or implied. See the License for the
15// specific language governing permissions and limitations
16// under the License.
17
18/**
19 * @fileoverview Utilities for working with WebDriver response objects.
20 * @see: hhttps://github.com/SeleniumHQ/selenium/wiki/JsonWireProtocol#responses
21 */
22
23goog.provide('bot.response');
24goog.provide('bot.response.ResponseObject');
25
26goog.require('bot.Error');
27goog.require('bot.ErrorCode');
28
29
30/**
31 * Type definition for a response object, as defined by the JSON wire protocol.
32 * @typedef {{status: bot.ErrorCode, value: (*|{message: string})}}
33 * @see https://github.com/SeleniumHQ/selenium/wiki/JsonWireProtocol#responses
34 */
35bot.response.ResponseObject;
36
37
38/**
39 * @param {*} value The value to test.
40 * @return {boolean} Whether the given value is a response object.
41 */
42bot.response.isResponseObject = function(value) {
43 return goog.isObject(value) && goog.isNumber(value['status']);
44};
45
46
47/**
48 * Creates a new success response object with the provided value.
49 * @param {*} value The response value.
50 * @return {!bot.response.ResponseObject} The new response object.
51 */
52bot.response.createResponse = function(value) {
53 if (bot.response.isResponseObject(value)) {
54 return /** @type {!bot.response.ResponseObject} */ (value);
55 }
56 return {
57 'status': bot.ErrorCode.SUCCESS,
58 'value': value
59 };
60};
61
62
63/**
64 * Converts an error value into its JSON representation as defined by the
65 * WebDriver wire protocol.
66 * @param {(bot.Error|Error|*)} error The error value to convert.
67 * @return {!bot.response.ResponseObject} The new response object.
68 */
69bot.response.createErrorResponse = function(error) {
70 if (bot.response.isResponseObject(error)) {
71 return /** @type {!bot.response.ResponseObject} */ (error);
72 }
73
74 var statusCode = error && goog.isNumber(error.code) ? error.code :
75 bot.ErrorCode.UNKNOWN_ERROR;
76 return {
77 'status': /** @type {bot.ErrorCode} */ (statusCode),
78 'value': {
79 'message': (error && error.message || error) + ''
80 }
81 };
82};
83
84
85/**
86 * Checks that a response object does not specify an error as defined by the
87 * WebDriver wire protocol. If the response object defines an error, it will
88 * be thrown. Otherwise, the response will be returned as is.
89 * @param {!bot.response.ResponseObject} responseObj The response object to
90 * check.
91 * @return {!bot.response.ResponseObject} The checked response object.
92 * @throws {bot.Error} If the response describes an error.
93 * @see https://github.com/SeleniumHQ/selenium/wiki/JsonWireProtocol#failed-commands
94 */
95bot.response.checkResponse = function(responseObj) {
96 var status = responseObj['status'];
97 if (status == bot.ErrorCode.SUCCESS) {
98 return responseObj;
99 }
100
101 // If status is not defined, assume an unknown error.
102 status = status || bot.ErrorCode.UNKNOWN_ERROR;
103
104 var value = responseObj['value'];
105 if (!value || !goog.isObject(value)) {
106 throw new bot.Error(status, value + '');
107 }
108
109 throw new bot.Error(status, value['message'] + '');
110};