Debian Codegraph @

closure-library/closure/goog/html/testing.js

raw
1 // Copyright 2013 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 /**
16 * @fileoverview Utilities to create arbitrary values of goog.html types for
17 * testing purposes. These utility methods perform no validation, and the
18 * resulting instances may violate type contracts.
19 *
20 * These methods are useful when types are constructed in a manner where using
21 * the production API is too inconvenient. Please do use the production API
22 * whenever possible; there is value in having tests reflect common usage and it
23 * avoids, by design, non-contract complying instances from being created.
24 */
25
26
27 goog.provide('goog.html.testing');
28 goog.setTestOnly();
29
30 goog.require('goog.html.SafeHtml');
31 goog.require('goog.html.SafeScript');
32 goog.require('goog.html.SafeStyle');
33 goog.require('goog.html.SafeStyleSheet');
34 goog.require('goog.html.SafeUrl');
35 goog.require('goog.html.TrustedResourceUrl');
36 goog.require('goog.testing.mockmatchers.ArgumentMatcher');
37
38
39 /**
40 * Creates a SafeHtml wrapping the given value. No validation is performed.
41 *
42 * This function is for use in tests only and must never be used in production
43 * code.
44 *
45 * @param {string} html The string to wrap into a SafeHtml.
46 * @param {?goog.i18n.bidi.Dir=} opt_dir The optional directionality of the
47 * SafeHtml to be constructed. A null or undefined value signifies an
48 * unknown directionality.
49 * @return {!goog.html.SafeHtml}
50 */
51 goog.html.testing.newSafeHtmlForTest = function(html, opt_dir) {
52 return goog.html.SafeHtml.createSafeHtmlSecurityPrivateDoNotAccessOrElse(
53 html, (opt_dir == undefined ? null : opt_dir));
54 };
55
56
57 /**
58 * Creates a SafeScript wrapping the given value. No validation is performed.
59 *
60 * This function is for use in tests only and must never be used in production
61 * code.
62 *
63 * @param {string} script The string to wrap into a SafeScript.
64 * @return {!goog.html.SafeScript}
65 */
66 goog.html.testing.newSafeScriptForTest = function(script) {
67 return goog.html.SafeScript.createSafeScriptSecurityPrivateDoNotAccessOrElse(
68 script);
69 };
70
71
72 /**
73 * Creates a SafeStyle wrapping the given value. No validation is performed.
74 *
75 * This function is for use in tests only and must never be used in production
76 * code.
77 *
78 * @param {string} style String to wrap into a SafeStyle.
79 * @return {!goog.html.SafeStyle}
80 */
81 goog.html.testing.newSafeStyleForTest = function(style) {
82 return goog.html.SafeStyle.createSafeStyleSecurityPrivateDoNotAccessOrElse(
83 style);
84 };
85
86
87 /**
88 * Creates a SafeStyleSheet wrapping the given value. No validation is
89 * performed.
90 *
91 * This function is for use in tests only and must never be used in production
92 * code.
93 *
94 * @param {string} styleSheet String to wrap into a SafeStyleSheet.
95 * @return {!goog.html.SafeStyleSheet}
96 */
97 goog.html.testing.newSafeStyleSheetForTest = function(styleSheet) {
98 return goog.html.SafeStyleSheet
99 .createSafeStyleSheetSecurityPrivateDoNotAccessOrElse(styleSheet);
100 };
101
102
103 /**
104 * Creates a SafeUrl wrapping the given value. No validation is performed.
105 *
106 * This function is for use in tests only and must never be used in production
107 * code.
108 *
109 * @param {string} url String to wrap into a SafeUrl.
110 * @return {!goog.html.SafeUrl}
111 */
112 goog.html.testing.newSafeUrlForTest = function(url) {
113 return goog.html.SafeUrl.createSafeUrlSecurityPrivateDoNotAccessOrElse(url);
114 };
115
116
117 /**
118 * Creates a TrustedResourceUrl wrapping the given value. No validation is
119 * performed.
120 *
121 * This function is for use in tests only and must never be used in production
122 * code.
123 *
124 * @param {string} url String to wrap into a TrustedResourceUrl.
125 * @return {!goog.html.TrustedResourceUrl}
126 */
127 goog.html.testing.newTrustedResourceUrlForTest = function(url) {
128 return goog.html.TrustedResourceUrl
129 .createTrustedResourceUrlSecurityPrivateDoNotAccessOrElse(url);
130 };
131
132
133 /**
134 * Creates an argument matcher for SafeHtml.
135 * @param {string|!goog.html.SafeHtml} expected
136 * @return {!goog.testing.mockmatchers.ArgumentMatcher}
137 */
138 goog.html.testing.matchSafeHtml = function(expected) {
139 if (expected instanceof goog.html.SafeHtml) {
140 expected = goog.html.SafeHtml.unwrap(expected);
141 }
142 return new goog.testing.mockmatchers.ArgumentMatcher(function(actual) {
143 return goog.html.SafeHtml.unwrap(actual) == expected;
144 });
145 };
146
147
148 /**
149 * Creates an argument matcher for SafeScript.
150 * @param {string|!goog.html.SafeScript} expected
151 * @return {!goog.testing.mockmatchers.ArgumentMatcher}
152 */
153 goog.html.testing.matchSafeScript = function(expected) {
154 if (expected instanceof goog.html.SafeScript) {
155 expected = goog.html.SafeScript.unwrap(expected);
156 }
157 return new goog.testing.mockmatchers.ArgumentMatcher(function(actual) {
158 return goog.html.SafeScript.unwrap(actual) == expected;
159 });
160 };
161
162
163 /**
164 * Creates an argument matcher for SafeStyle.
165 * @param {string|!goog.html.SafeStyle} expected
166 * @return {!goog.testing.mockmatchers.ArgumentMatcher}
167 */
168 goog.html.testing.matchSafeStyle = function(expected) {
169 if (expected instanceof goog.html.SafeStyle) {
170 expected = goog.html.SafeStyle.unwrap(expected);
171 }
172 return new goog.testing.mockmatchers.ArgumentMatcher(function(actual) {
173 return goog.html.SafeStyle.unwrap(actual) == expected;
174 });
175 };
176
177
178 /**
179 * Creates an argument matcher for SafeStyleSheet.
180 * @param {string|!goog.html.SafeStyleSheet} expected
181 * @return {!goog.testing.mockmatchers.ArgumentMatcher}
182 */
183 goog.html.testing.matchSafeStyleSheet = function(expected) {
184 if (expected instanceof goog.html.SafeStyleSheet) {
185 expected = goog.html.SafeStyleSheet.unwrap(expected);
186 }
187 return new goog.testing.mockmatchers.ArgumentMatcher(function(actual) {
188 return goog.html.SafeStyleSheet.unwrap(actual) == expected;
189 });
190 };
191
192
193 /**
194 * Creates an argument matcher for SafeUrl.
195 * @param {string|!goog.html.SafeUrl} expected
196 * @return {!goog.testing.mockmatchers.ArgumentMatcher}
197 */
198 goog.html.testing.matchSafeUrl = function(expected) {
199 if (expected instanceof goog.html.SafeUrl) {
200 expected = goog.html.SafeUrl.unwrap(expected);
201 }
202 return new goog.testing.mockmatchers.ArgumentMatcher(function(actual) {
203 return goog.html.SafeUrl.unwrap(actual) == expected;
204 });
205 };
206
207
208 /**
209 * Creates an argument matcher for TrustedResourceUrl.
210 * @param {string|!goog.html.TrustedResourceUrl} expected
211 * @return {!goog.testing.mockmatchers.ArgumentMatcher}
212 */
213 goog.html.testing.matchTrustedResourceUrl = function(expected) {
214 if (expected instanceof goog.html.TrustedResourceUrl) {
215 expected = goog.html.TrustedResourceUrl.unwrap(expected);
216 }
217 return new goog.testing.mockmatchers.ArgumentMatcher(function(actual) {
218 return goog.html.TrustedResourceUrl.unwrap(actual) == expected;
219 });
220 };
221
222
223 /**
224 * Equality tester to be used in Jasmine tests. Example:
225 *
226 * beforeEach(function() {
227 * jasmine.addCustomEqualityTester(
228 * goog.html.testing.checkTypedStringEquality);
229 * });
230 *
231 * it('typed string value matches same string', function() {
232 * expect(f).toHaveBeenCalledWith('expected');
233 * });
234 *
235 * it('typed string value matches same type and string', function() {
236 * expect(f).toHaveBeenCalledWith(goog.string.Const.from('expected'));
237 * });
238 *
239 * @param {*} actual Handles goog.string.TypedString.
240 * @param {*} expected Handles goog.string.TypedString or string.
241 * @return {boolean|undefined} Undefined if not called with
242 * goog.string.TypedString, true if typed strings equal, false if not.
243 */
244 goog.html.testing.checkTypedStringEquality = function(actual, expected) {
245 if (actual.implementsGoogStringTypedString) {
246 if (expected.implementsGoogStringTypedString) {
247 if (!(actual instanceof expected.constructor)) {
248 return false;
249 }
250 expected = expected.getTypedStringValue();
251 }
252 return actual.getTypedStringValue() == expected;
253 }
254 };