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 | }; |