Debian Codegraph @

closure-library/closure/goog/dom/asserts.js

raw
1 // Copyright 2017 The Closure Library Authors. 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 goog.provide('goog.dom.asserts');
16
17 goog.require('goog.asserts');
18
19 /**
20 * @fileoverview Custom assertions to ensure that an element has the appropriate
21 * type.
22 *
23 * Using a goog.dom.safe wrapper on an object on the incorrect type (via an
24 * incorrect static type cast) can result in security bugs: For instance,
25 * g.d.s.setAnchorHref ensures that the URL assigned to the .href attribute
26 * satisfies the SafeUrl contract, i.e., is safe to dereference as a hyperlink.
27 * However, the value assigned to a HTMLLinkElement's .href property requires
28 * the stronger TrustedResourceUrl contract, since it can refer to a stylesheet.
29 * Thus, using g.d.s.setAnchorHref on an (incorrectly statically typed) object
30 * of type HTMLLinkElement can result in a security vulnerability.
31 * Assertions of the correct run-time type help prevent such incorrect use.
32 *
33 * In some cases, code using the DOM API is tested using mock objects (e.g., a
34 * plain object such as {'href': url} instead of an actual Location object).
35 * To allow such mocking, the assertions permit objects of types that are not
36 * relevant DOM API objects at all (for instance, not Element or Location).
37 *
38 * Note that instanceof checks don't work straightforwardly in older versions of
39 * IE, or across frames (see,
40 * http://stackoverflow.com/questions/384286/javascript-isdom-how-do-you-check-if-a-javascript-object-is-a-dom-object,
41 * http://stackoverflow.com/questions/26248599/instanceof-htmlelement-in-iframe-is-not-element-or-object).
42 *
43 * Hence, these assertions may pass vacuously in such scenarios. The resulting
44 * risk of security bugs is limited by the following factors:
45 * - A bug can only arise in scenarios involving incorrect static typing (the
46 * wrapper methods are statically typed to demand objects of the appropriate,
47 * precise type).
48 * - Typically, code is tested and exercised in multiple browsers.
49 */
50
51 /**
52 * Asserts that a given object is a Location.
53 *
54 * To permit this assertion to pass in the context of tests where DOM APIs might
55 * be mocked, also accepts any other type except for subtypes of {!Element}.
56 * This is to ensure that, for instance, HTMLLinkElement is not being used in
57 * place of a Location, since this could result in security bugs due to stronger
58 * contracts required for assignments to the href property of the latter.
59 *
60 * @param {?Object} o The object whose type to assert.
61 * @return {!Location}
62 */
63 goog.dom.asserts.assertIsLocation = function(o) {
64 if (goog.asserts.ENABLE_ASSERTS) {
65 var win = goog.dom.asserts.getWindow_(o);
66 if (typeof win.Location != 'undefined' &&
67 typeof win.Element != 'undefined') {
68 goog.asserts.assert(
69 o && (o instanceof win.Location || !(o instanceof win.Element)),
70 'Argument is not a Location (or a non-Element mock); got: %s',
71 goog.dom.asserts.debugStringForType_(o));
72 }
73 }
74 return /** @type {!Location} */ (o);
75 };
76
77
78 /**
79 * Asserts that a given object is either the given subtype of Element
80 * or a non-Element, non-Location Mock.
81 *
82 * To permit this assertion to pass in the context of tests where DOM
83 * APIs might be mocked, also accepts any other type except for
84 * subtypes of {!Element}. This is to ensure that, for instance,
85 * HTMLScriptElement is not being used in place of a HTMLImageElement,
86 * since this could result in security bugs due to stronger contracts
87 * required for assignments to the src property of the latter.
88 *
89 * The DOM type is looked up in the window the object belongs to. In
90 * some contexts, this might not be possible (e.g. when running tests
91 * outside a browser, cross-domain lookup). In this case, the
92 * assertions are skipped.
93 *
94 * @param {?Object} o The object whose type to assert.
95 * @param {string} typename The name of the DOM type.
96 * @return {!Element} The object.
97 * @private
98 */
99 // TODO(bangert): Make an analog of goog.dom.TagName to correctly handle casts?
100 goog.dom.asserts.assertIsElementType_ = function(o, typename) {
101 if (goog.asserts.ENABLE_ASSERTS) {
102 var win = goog.dom.asserts.getWindow_(o);
103 if (typeof win[typename] != 'undefined' &&
104 typeof win.Location != 'undefined' &&
105 typeof win.Element != 'undefined') {
106 goog.asserts.assert(
107 o &&
108 (o instanceof win[typename] ||
109 !((o instanceof win.Location) || (o instanceof win.Element))),
110 'Argument is not a %s (or a non-Element, non-Location mock); got: %s',
111 typename, goog.dom.asserts.debugStringForType_(o));
112 }
113 }
114 return /** @type {!Element} */ (o);
115 };
116
117 /**
118 * Asserts that a given object is a HTMLAnchorElement.
119 *
120 * To permit this assertion to pass in the context of tests where elements might
121 * be mocked, also accepts objects that are not of type Location nor a subtype
122 * of Element.
123 *
124 * @param {?Object} o The object whose type to assert.
125 * @return {!HTMLAnchorElement}
126 */
127 goog.dom.asserts.assertIsHTMLAnchorElement = function(o) {
128 return /** @type {!HTMLAnchorElement} */ (
129 goog.dom.asserts.assertIsElementType_(o, 'HTMLAnchorElement'));
130 };
131
132 /**
133 * Asserts that a given object is a HTMLButtonElement.
134 *
135 * To permit this assertion to pass in the context of tests where elements might
136 * be mocked, also accepts objects that are not a subtype of Element.
137 *
138 * @param {?Object} o The object whose type to assert.
139 * @return {!HTMLButtonElement}
140 */
141 goog.dom.asserts.assertIsHTMLButtonElement = function(o) {
142 return /** @type {!HTMLButtonElement} */ (
143 goog.dom.asserts.assertIsElementType_(o, 'HTMLButtonElement'));
144 };
145
146 /**
147 * Asserts that a given object is a HTMLLinkElement.
148 *
149 * To permit this assertion to pass in the context of tests where elements might
150 * be mocked, also accepts objects that are not a subtype of Element.
151 *
152 * @param {?Object} o The object whose type to assert.
153 * @return {!HTMLLinkElement}
154 */
155 goog.dom.asserts.assertIsHTMLLinkElement = function(o) {
156 return /** @type {!HTMLLinkElement} */ (
157 goog.dom.asserts.assertIsElementType_(o, 'HTMLLinkElement'));
158 };
159
160 /**
161 * Asserts that a given object is a HTMLImageElement.
162 *
163 * To permit this assertion to pass in the context of tests where elements might
164 * be mocked, also accepts objects that are not a subtype of Element.
165 *
166 * @param {?Object} o The object whose type to assert.
167 * @return {!HTMLImageElement}
168 */
169 goog.dom.asserts.assertIsHTMLImageElement = function(o) {
170 return /** @type {!HTMLImageElement} */ (
171 goog.dom.asserts.assertIsElementType_(o, 'HTMLImageElement'));
172 };
173
174 /**
175 * Asserts that a given object is a HTMLVideoElement.
176 *
177 * To permit this assertion to pass in the context of tests where elements might
178 * be mocked, also accepts objects that are not a subtype of Element.
179 *
180 * @param {?Object} o The object whose type to assert.
181 * @return {!HTMLVideoElement}
182 */
183 goog.dom.asserts.assertIsHTMLVideoElement = function(o) {
184 return /** @type {!HTMLVideoElement} */ (
185 goog.dom.asserts.assertIsElementType_(o, 'HTMLVideoElement'));
186 };
187
188 /**
189 * Asserts that a given object is a HTMLInputElement.
190 *
191 * To permit this assertion to pass in the context of tests where elements might
192 * be mocked, also accepts objects that are not a subtype of Element.
193 *
194 * @param {?Object} o The object whose type to assert.
195 * @return {!HTMLInputElement}
196 */
197 goog.dom.asserts.assertIsHTMLInputElement = function(o) {
198 return /** @type {!HTMLInputElement} */ (
199 goog.dom.asserts.assertIsElementType_(o, 'HTMLInputElement'));
200 };
201
202 /**
203 * Asserts that a given object is a HTMLEmbedElement.
204 *
205 * To permit this assertion to pass in the context of tests where elements might
206 * be mocked, also accepts objects that are not a subtype of Element.
207 *
208 * @param {?Object} o The object whose type to assert.
209 * @return {!HTMLEmbedElement}
210 */
211 goog.dom.asserts.assertIsHTMLEmbedElement = function(o) {
212 return /** @type {!HTMLEmbedElement} */ (
213 goog.dom.asserts.assertIsElementType_(o, 'HTMLEmbedElement'));
214 };
215
216 /**
217 * Asserts that a given object is a HTMLFormElement.
218 *
219 * To permit this assertion to pass in the context of tests where elements might
220 * be mocked, also accepts objects that are not a subtype of Element.
221 *
222 * @param {?Object} o The object whose type to assert.
223 * @return {!HTMLFormElement}
224 */
225 goog.dom.asserts.assertIsHTMLFormElement = function(o) {
226 return /** @type {!HTMLFormElement} */ (
227 goog.dom.asserts.assertIsElementType_(o, 'HTMLFormElement'));
228 };
229
230 /**
231 * Asserts that a given object is a HTMLFrameElement.
232 *
233 * To permit this assertion to pass in the context of tests where elements might
234 * be mocked, also accepts objects that are not a subtype of Element.
235 *
236 * @param {?Object} o The object whose type to assert.
237 * @return {!HTMLFrameElement}
238 */
239 goog.dom.asserts.assertIsHTMLFrameElement = function(o) {
240 return /** @type {!HTMLFrameElement} */ (
241 goog.dom.asserts.assertIsElementType_(o, 'HTMLFrameElement'));
242 };
243
244 /**
245 * Asserts that a given object is a HTMLIFrameElement.
246 *
247 * To permit this assertion to pass in the context of tests where elements might
248 * be mocked, also accepts objects that are not a subtype of Element.
249 *
250 * @param {?Object} o The object whose type to assert.
251 * @return {!HTMLIFrameElement}
252 */
253 goog.dom.asserts.assertIsHTMLIFrameElement = function(o) {
254 return /** @type {!HTMLIFrameElement} */ (
255 goog.dom.asserts.assertIsElementType_(o, 'HTMLIFrameElement'));
256 };
257
258 /**
259 * Asserts that a given object is a HTMLObjectElement.
260 *
261 * To permit this assertion to pass in the context of tests where elements might
262 * be mocked, also accepts objects that are not a subtype of Element.
263 *
264 * @param {?Object} o The object whose type to assert.
265 * @return {!HTMLObjectElement}
266 */
267 goog.dom.asserts.assertIsHTMLObjectElement = function(o) {
268 return /** @type {!HTMLObjectElement} */ (
269 goog.dom.asserts.assertIsElementType_(o, 'HTMLObjectElement'));
270 };
271
272 /**
273 * Asserts that a given object is a HTMLScriptElement.
274 *
275 * To permit this assertion to pass in the context of tests where elements might
276 * be mocked, also accepts objects that are not a subtype of Element.
277 *
278 * @param {?Object} o The object whose type to assert.
279 * @return {!HTMLScriptElement}
280 */
281 goog.dom.asserts.assertIsHTMLScriptElement = function(o) {
282 return /** @type {!HTMLScriptElement} */ (
283 goog.dom.asserts.assertIsElementType_(o, 'HTMLScriptElement'));
284 };
285
286 /**
287 * Returns a string representation of a value's type.
288 *
289 * @param {*} value An object, or primitive.
290 * @return {string} The best display name for the value.
291 * @private
292 */
293 goog.dom.asserts.debugStringForType_ = function(value) {
294 if (goog.isObject(value)) {
295 return value.constructor.displayName || value.constructor.name ||
296 Object.prototype.toString.call(value);
297 } else {
298 return value === undefined ? 'undefined' :
299 value === null ? 'null' : typeof value;
300 }
301 };
302
303 /**
304 * Gets window of element.
305 * @param {?Object} o
306 * @return {!Window}
307 * @private
308 */
309 goog.dom.asserts.getWindow_ = function(o) {
310 var doc = o && o.ownerDocument;
311 var win = doc && /** @type {?Window} */ (doc.defaultView || doc.parentWindow);
312 return win || /** @type {!Window} */ (goog.global);
313 };