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
20goog.provide('bot.response');
21goog.provide('bot.response.ResponseObject');
22
23goog.require('bot.Error');
24goog.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 */
32bot.response.ResponseObject;
33
34
35/**
36 * @param {*} value The value to test.
37 * @return {boolean} Whether the given value is a response object.
38 */
39bot.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 */
49bot.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 */
66bot.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 */
92bot.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};