# 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 |
23 | goog.provide('bot.response');
24 | goog.provide('bot.response.ResponseObject');
25 |
26 | goog.require('bot.Error');
27 | goog.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 | */
35 | bot.response.ResponseObject;
36 |
37 |
38 | /**
39 | * @param {*} value The value to test.
40 | * @return {boolean} Whether the given value is a response object.
41 | */
42 | bot.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 | */
52 | bot.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 | */
69 | bot.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 | */
95 | bot.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 | };