# lib/atoms/response.js

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