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: https://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
};
111

112