// Licensed to the Software Freedom Conservancy (SFC) under one

// or more contributor license agreements. See the NOTICE file

// distributed with this work for additional information

// regarding copyright ownership. The SFC licenses this file

// to you under the Apache License, Version 2.0 (the

// "License"); you may not use this file except in compliance

// with the License. You may obtain a copy of the License at

//

// http://www.apache.org/licenses/LICENSE-2.0

//

// Unless required by applicable law or agreed to in writing,

// software distributed under the License is distributed on an

// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY

// KIND, either express or implied. See the License for the

// specific language governing permissions and limitations

// under the License.

/**

* @fileoverview Assertions and expectation utilities for use in WebDriver test

* cases.

*/

goog.provide('webdriver.testing.Assertion');

goog.provide('webdriver.testing.ContainsMatcher');

goog.provide('webdriver.testing.NegatedAssertion');

goog.provide('webdriver.testing.assert');

goog.provide('webdriver.testing.asserts');

goog.require('goog.array');

goog.require('goog.labs.testing.CloseToMatcher');

goog.require('goog.labs.testing.EndsWithMatcher');

goog.require('goog.labs.testing.EqualToMatcher');

goog.require('goog.labs.testing.EqualsMatcher');

goog.require('goog.labs.testing.GreaterThanEqualToMatcher');

goog.require('goog.labs.testing.GreaterThanMatcher');

goog.require('goog.labs.testing.LessThanEqualToMatcher');

goog.require('goog.labs.testing.LessThanMatcher');

goog.require('goog.labs.testing.InstanceOfMatcher');

goog.require('goog.labs.testing.IsNotMatcher');

goog.require('goog.labs.testing.IsNullMatcher');

goog.require('goog.labs.testing.IsNullOrUndefinedMatcher');

goog.require('goog.labs.testing.IsUndefinedMatcher');

goog.require('goog.labs.testing.Matcher');

goog.require('goog.labs.testing.ObjectEqualsMatcher');

goog.require('goog.labs.testing.RegexMatcher');

goog.require('goog.labs.testing.StartsWithMatcher');

goog.require('goog.labs.testing.assertThat');

goog.require('goog.string');

goog.require('webdriver.promise');

/**

* Accepts strins or array-like structures that contain {@code value}.

* @param {*} value The value to check for.

* @constructor

* @implements {goog.labs.testing.Matcher}

*/

webdriver.testing.ContainsMatcher = function(value) {

/** @private {*} */

this.value_ = value;

};

/** @override */

webdriver.testing.ContainsMatcher.prototype.matches = function(actualValue) {

if (goog.isString(actualValue)) {

return goog.string.contains(

actualValue, /** @type {string} */(this.value_));

} else {

return goog.array.contains(

/** @type {goog.array.ArrayLike} */(actualValue), this.value_);

}

};

/** @override */

webdriver.testing.ContainsMatcher.prototype.describe = function(actualValue) {

return actualValue + ' does not contain ' + this.value_;

};

/**

* Utility for performing assertions against a given {@code value}. If the

* value is a {@link webdriver.promise.Promise}, this assertion will wait

* for it to resolve before applying any matchers.

* @param {*} value The value to wrap and apply matchers to.

* @constructor

*/

webdriver.testing.Assertion = function(value) {

/** @private {*} */

this.value_ = value;

if (!(this instanceof webdriver.testing.NegatedAssertion)) {

/**

* A self reference provided for writing fluent assertions:

* webdriver.testing.assert(x).is.equalTo(y);

* @type {!webdriver.testing.Assertion}

*/

this.is = this;

/**

* Negates any matchers applied to this instance's value:

* webdriver.testing.assert(x).not.equalTo(y);

* @type {!webdriver.testing.NegatedAssertion}

*/

this.not = new webdriver.testing.NegatedAssertion(value);

}

};

/**

* Wraps an object literal implementing the Matcher interface. This is used

* to appease the Closure compiler, which will not treat an object literal as

* implementing an interface.

* @param {{matches: function(*): boolean, describe: function(): string}} obj

* The object literal to delegate to.

* @constructor

* @implements {goog.labs.testing.Matcher}

* @private

*/

webdriver.testing.Assertion.DelegatingMatcher_ = function(obj) {

/** @override */

this.matches = function(value) {

return obj.matches(value);

};

/** @override */

this.describe = function() {

return obj.describe();

};

};

/**

* Asserts that the given {@code matcher} accepts the value wrapped by this

* instance. If the wrapped value is a promise, this function will defer

* applying the assertion until the value has been resolved. Otherwise, it

* will be applied immediately.

* @param {!goog.labs.testing.Matcher} matcher The matcher to apply

* @param {string=} opt_message A message to include if the matcher does not

* accept the value wrapped by this assertion.

* @return {webdriver.promise.Promise} The deferred assertion result, or

* {@code null} if the assertion was immediately applied.

* @protected

*/

webdriver.testing.Assertion.prototype.apply = function(matcher, opt_message) {

var result = null;

if (webdriver.promise.isPromise(this.value_)) {

result = webdriver.promise.when(this.value_, function(value) {

goog.labs.testing.assertThat(value, matcher, opt_message);

});

} else {

goog.labs.testing.assertThat(this.value_, matcher, opt_message);

}

return result;

};

/**

* Asserts that the value managed by this assertion is a number strictly

* greater than {@code value}.

* @param {number} value The minimum value.

* @param {string=} opt_message A message to include if the matcher does not

* accept the value wrapped by this assertion.

* @return {webdriver.promise.Promise} The assertion result.

*/

webdriver.testing.Assertion.prototype.greaterThan = function(

value, opt_message) {

return this.apply(

new goog.labs.testing.GreaterThanMatcher(value), opt_message);

};

/**

* Asserts that the value managed by this assertion is a number >= the given

* value.

* @param {number} value The minimum value.

* @param {string=} opt_message A message to include if the matcher does not

* accept the value wrapped by this assertion.

* @return {webdriver.promise.Promise} The assertion result.

*/

webdriver.testing.Assertion.prototype.greaterThanEqualTo = function(

value, opt_message) {

return this.apply(

new goog.labs.testing.GreaterThanEqualToMatcher(value), opt_message);

};

/**

* Asserts that the value managed by this assertion is a number strictly less

* than the given value.

* @param {number} value The maximum value.

* @param {string=} opt_message A message to include if the matcher does not

* accept the value wrapped by this assertion.

* @return {webdriver.promise.Promise} The assertion result.

*/

webdriver.testing.Assertion.prototype.lessThan = function(value, opt_message) {

return this.apply(

new goog.labs.testing.LessThanMatcher(value), opt_message);

};

/**

* Asserts that the value managed by this assertion is a number <= the given

* value.

* @param {number} value The maximum value.

* @param {string=} opt_message A message to include if the matcher does not

* accept the value wrapped by this assertion.

* @return {webdriver.promise.Promise} The assertion result.

*/

webdriver.testing.Assertion.prototype.lessThanEqualTo = function(

value, opt_message) {

return this.apply(

new goog.labs.testing.LessThanEqualToMatcher(value), opt_message);

};

/**

* Asserts that the wrapped value is a number within a given distance of an

* expected value.

* @param {number} value The expected value.

* @param {number} range The maximum amount the actual value is permitted to

* differ from the expected value.

* @param {string=} opt_message A message to include if the matcher does not

* accept the value wrapped by this assertion.

* @return {webdriver.promise.Promise} The assertion result.

*/

webdriver.testing.Assertion.prototype.closeTo = function(

value, range, opt_message) {

return this.apply(

new goog.labs.testing.CloseToMatcher(value, range), opt_message);

};

/**

* Asserts that the wrapped value is an instance of the given class.

* @param {!Function} ctor The expected class constructor.

* @param {string=} opt_message A message to include if the matcher does not

* accept the value wrapped by this assertion.

* @return {webdriver.promise.Promise} The assertion result.

*/

webdriver.testing.Assertion.prototype.instanceOf = function(ctor, opt_message) {

return this.apply(

new goog.labs.testing.InstanceOfMatcher(ctor), opt_message);

};

/**

* Asserts that the wrapped value is null.

* @param {string=} opt_message A message to include if the matcher does not

* accept the value wrapped by this assertion.

* @return {webdriver.promise.Promise} The assertion result.

*/

webdriver.testing.Assertion.prototype.isNull = function(opt_message) {

return this.apply(new goog.labs.testing.IsNullMatcher(), opt_message);

};

/**

* Asserts that the wrapped value is undefined.

* @param {string=} opt_message A message to include if the matcher does not

* accept the value wrapped by this assertion.

* @return {webdriver.promise.Promise} The assertion result.

*/

webdriver.testing.Assertion.prototype.isUndefined = function(opt_message) {

return this.apply(new goog.labs.testing.IsUndefinedMatcher(), opt_message);

};

/**

* Asserts that the wrapped value is null or undefined.

* @param {string=} opt_message A message to include if the matcher does not

* accept the value wrapped by this assertion.

* @return {webdriver.promise.Promise} The assertion result.

*/

webdriver.testing.Assertion.prototype.isNullOrUndefined = function(

opt_message) {

return this.apply(

new goog.labs.testing.IsNullOrUndefinedMatcher(), opt_message);

};

/**

* Asserts that the wrapped value is a string or array-like structure

* containing the given value.

* @param {*} value The expected value.

* @param {string=} opt_message A message to include if the matcher does not

* accept the value wrapped by this assertion.

* @return {webdriver.promise.Promise} The assertion result.

*/

webdriver.testing.Assertion.prototype.contains = function(value, opt_message) {

return this.apply(

new webdriver.testing.ContainsMatcher(value), opt_message);

};

/**

* Asserts that the wrapped value is a string ending with the given suffix.

* @param {string} suffix The expected suffix.

* @param {string=} opt_message A message to include if the matcher does not

* accept the value wrapped by this assertion.

* @return {webdriver.promise.Promise} The assertion result.

*/

webdriver.testing.Assertion.prototype.endsWith = function(

suffix, opt_message) {

return this.apply(

new goog.labs.testing.EndsWithMatcher(suffix), opt_message);

};

/**

* Asserts that the wrapped value is a string starting with the given prefix.

* @param {string} prefix The expected prefix.

* @param {string=} opt_message A message to include if the matcher does not

* accept the value wrapped by this assertion.

* @return {webdriver.promise.Promise} The assertion result.

*/

webdriver.testing.Assertion.prototype.startsWith = function(

prefix, opt_message) {

return this.apply(

new goog.labs.testing.StartsWithMatcher(prefix), opt_message);

};

/**

* Asserts that the wrapped value is a string that matches the given RegExp.

* @param {!RegExp} regex The regex to test.

* @param {string=} opt_message A message to include if the matcher does not

* accept the value wrapped by this assertion.

* @return {webdriver.promise.Promise} The assertion result.

*/

webdriver.testing.Assertion.prototype.matches = function(regex, opt_message) {

return this.apply(new goog.labs.testing.RegexMatcher(regex), opt_message);

};

/**

* Asserts that the value managed by this assertion is strictly equal to the

* given {@code value}.

* @param {*} value The expected value.

* @param {string=} opt_message A message to include if the matcher does not

* accept the value wrapped by this assertion.

* @return {webdriver.promise.Promise} The assertion result.

*/

webdriver.testing.Assertion.prototype.equalTo = function(value, opt_message) {

return this.apply(webdriver.testing.asserts.equalTo(value), opt_message);

};

/**

* Asserts that the value managed by this assertion is strictly true.

* @return {webdriver.promise.Promise} The assertion result.

*/

webdriver.testing.Assertion.prototype.isTrue = function() {

return this.equalTo(true);

};

/**

* Asserts that the value managed by this assertion is strictly false.

* @return {webdriver.promise.Promise} The assertion result.

*/

webdriver.testing.Assertion.prototype.isFalse = function() {

return this.equalTo(false);

};

/**

* An assertion that negates any applied matchers.

* @param {*} value The value to perform assertions on.

* @constructor

* @extends {webdriver.testing.Assertion}

*/

webdriver.testing.NegatedAssertion = function(value) {

goog.base(this, value);

this.value = value;

};

goog.inherits(

webdriver.testing.NegatedAssertion, webdriver.testing.Assertion);

/** @override */

webdriver.testing.NegatedAssertion.prototype.apply = function(

matcher, opt_message) {

matcher = new goog.labs.testing.IsNotMatcher(matcher);

return goog.base(this, 'apply', matcher, opt_message);

};

/**

* Creates a new assertion.

* @param {*} value The value to perform an assertion on.

* @return {!webdriver.testing.Assertion} The new assertion.

*/

webdriver.testing.assert = function(value) {

return new webdriver.testing.Assertion(value);

};

/**

* Registers a new assertion to expose from the

* {@link webdriver.testing.Assertion} prototype.

* @param {string} name The assertion name.

* @param {(function(new: goog.labs.testing.Matcher, *)|

* {matches: function(*): boolean,

* describe: function(): string})} matcherTemplate Either the

* matcher constructor to use, or an object literal defining a matcher.

*/

webdriver.testing.assert.register = function(name, matcherTemplate) {

webdriver.testing.Assertion.prototype[name] = function(value, opt_message) {

var matcher;

if (goog.isFunction(matcherTemplate)) {

var ctor = /** @type {function(new: goog.labs.testing.Matcher, *)} */ (

matcherTemplate);

matcher = new ctor(value);

} else {

matcher = new webdriver.testing.Assertion.DelegatingMatcher_(value);

}

return this.apply(matcher, opt_message);

};

};

/**

* Asserts that a matcher accepts a given value. This function has two

* signatures based on the number of arguments:

*

* Two arguments:

* assertThat(actualValue, matcher)

* Three arguments:

* assertThat(failureMessage, actualValue, matcher)

*

* @param {*} failureMessageOrActualValue Either a failure message or the value

* to apply to the given matcher.

* @param {*} actualValueOrMatcher Either the value to apply to the given

* matcher, or the matcher itself.

* @param {goog.labs.testing.Matcher=} opt_matcher The matcher to use;

* ignored unless this function is invoked with three arguments.

* @return {!webdriver.promise.Promise} The assertion result.

* @deprecated Use webdriver.testing.asserts.assert instead.

*/

webdriver.testing.asserts.assertThat = function(

failureMessageOrActualValue, actualValueOrMatcher, opt_matcher) {

var args = goog.array.slice(arguments, 0);

var message = args.length > 2 ? args.shift() : '';

if (message) message += '\n';

var actualValue = args.shift();

var matcher = args.shift();

return webdriver.promise.when(actualValue, function(value) {

goog.labs.testing.assertThat(value, matcher, message);

});

};

/**

* Creates an equality matcher.

* @param {*} expected The expected value.

* @return {!goog.labs.testing.Matcher} The new matcher.

*/

webdriver.testing.asserts.equalTo = function(expected) {

if (goog.isString(expected)) {

return new goog.labs.testing.EqualsMatcher(expected);

} else if (goog.isNumber(expected)) {

return new goog.labs.testing.EqualToMatcher(expected);

} else {

return new goog.labs.testing.ObjectEqualsMatcher(

/** @type {!Object} */ (expected));

}

};

goog.exportSymbol('assertThat', webdriver.testing.asserts.assertThat);

// Mappings for goog.labs.testing matcher functions to the legacy

// webdriver.testing.asserts matchers.

goog.exportSymbol('contains', containsString);

goog.exportSymbol('equalTo', webdriver.testing.asserts.equalTo);

goog.exportSymbol('equals', webdriver.testing.asserts.equalTo);

goog.exportSymbol('is', webdriver.testing.asserts.equalTo);

goog.exportSymbol('not', isNot);

goog.exportSymbol('or', anyOf);