Merge pull request #144 from san650/fix-jsdoc

Re-add JSDoc documentation that vanished during merge

package.json

@@ -53,6 +53,8 @@
   },
   "keywords": [
     "acceptance",
+    "integration",
+    "components",
     "ember",
     "ember-addon",
     "ember-cli",

test-support/page-object/actions/clickable.js

@@ -1,19 +1,54 @@
 import { findElementWithAssert, buildSelector, getContext } from '../helpers';
 
 /**
- * Creates an action to click an element
+ * Clicks elements matched by a selector.
  *
  * @example
  *
- *   var page = PageObject.create({
- *     submit: clickable('button[type=submit]')
- *   });
+ * // <button class="continue">Continue<button>
+ * // <button>Cancel</button>
  *
- *   page.submit();
+ * const page = PageObject.create({
+ *   continue: clickable('button.continue')
+ * });
+ *
+ * // clicks on element with selector 'button.continue'
+ * page.continue();
+ *
+ * @example
+ *
+ * // <div class="scope">
+ * //   <button>Continue<button>
+ * // </div>
+ * // <button>Cancel</button>
+ *
+ * const page = PageObject.create({
+ *   continue: clickable('button.continue', { scope: '.scope' })
+ * });
+ *
+ * // clicks on element with selector '.scope button.continue'
+ * page.continue();
+ *
+ * @example
+ *
+ * // <div class="scope">
+ * //   <button>Continue<button>
+ * // </div>
+ * // <button>Cancel</button>
+ *
+ * const page = PageObject.create({
+ *   scope: '.scope',
+ *   continue: clickable('button.continue')
+ * });
+ *
+ * // clicks on element with selector '.scope button.continue'
+ * page.continue();
+ *
+ * @public
  *
  * @param {string} selector - CSS selector of the element to click
  * @param {Object} options - Additional options
- * @param {string} options.scope - Overrides parent scope
+ * @param {string} options.scope - Nests provided scope within parent's scope
  * @param {number} options.at - Reduce the set of matched elements to the one at the specified index
  * @param {boolean} options.resetScope - Ignore parent scope
  * @return {Descriptor}

test-support/page-object/actions/fillable.js

@@ -2,21 +2,67 @@ import Ember from 'ember';
 import { findElementWithAssert, buildSelector, getContext } from '../helpers';
 
 /**
- * Creates an action to fill in an input
+ * Fills in an input matched by a selector.
  *
  * @example
  *
- *   var page = PageObject.create({
- *     name: fillable('#name')
- *   });
+ * // <input value="">
  *
- *   page.name('John Doe');
+ * const page = PageObject.create({
+ *   fillIn: PageObject.fillable('input')
+ * });
  *
- * @param {string} selector - CSS selector of the element to fill
+ * // result: <input value="John Doe">
+ * page.fillIn('John Doe');
+ *
+ * @example
+ *
+ * // <div class="name">
+ * //   <input value="">
+ * // </div>
+ * // <div class="last-name">
+ * //   <input value= "">
+ * // </div>
+ *
+ * const page = PageObject.create({
+ *   fillInName: PageObject.fillable('input', { scope: '.name' })
+ * });
+ *
+ * page.fillInName('John Doe');
+ *
+ * // result
+ * // <div class="name">
+ * //   <input value="John Doe">
+ * // </div>
+ *
+ * @example
+ *
+ * // <div class="name">
+ * //   <input value="">
+ * // </div>
+ * // <div class="last-name">
+ * //   <input value= "">
+ * // </div>
+ *
+ * const page = PageObject.create({
+ *   scope: 'name',
+ *   fillInName: PageObject.fillable('input')
+ * });
+ *
+ * page.fillInName('John Doe');
+ *
+ * // result
+ * // <div class="name">
+ * //   <input value="John Doe">
+ * // </div>
+ *
+ * @public
+ *
+ * @param {string} selector - CSS selector of the element to look for text
  * @param {Object} options - Additional options
- * @param {string} options.scope - Overrides parent scope
+ * @param {string} options.scope - Nests provided scope within parent's scope
  * @param {number} options.at - Reduce the set of matched elements to the one at the specified index
- * @param {boolean} options.resetScope - Ignore parent scope
+ * @param {boolean} options.resetScope - Override parent's scope
  * @return {Descriptor}
  */
 export function fillable(selector, options = {}) {

test-support/page-object/predicates/contains.js

@@ -1,22 +1,83 @@
 import { findElementWithAssert, every } from '../helpers';
 
 /**
- * Creates a predicate to validate if an element contains a subtext
+ * Returns a boolean representing whether an element or a set of elements contains the specified text.
  *
  * @example
- *   <h1> Page Title </h1>
  *
- *   var page = PageObject.create({
- *     titleIncludes: contains('h1')
- *   });
+ * // Lorem <span>ipsum</span>
  *
- *   assert.ok(page.titleIncludes('Page'));
+ * const page = PageObject.create({
+ *   spanContains: PageObject.contains('span')
+ * });
+ *
+ * assert.ok(page.spanContains('ipsum'));
+ *
+ * @example
+ *
+ * // <span>lorem</span>
+ * // <span>ipsum</span>
+ * // <span>dolor</span>
+ *
+ * const page = PageObject.create({
+ *   spansContain: PageObject.contains('span', { multiple: true })
+ * });
+ *
+ * // not all spans contain 'lorem'
+ * assert.notOk(page.spansContain('lorem'));
+ *
+ * @example
+ *
+ * // <span>super text</span>
+ * // <span>regular text</span>
+ *
+ * const page = PageObject.create({
+ *   spansContain: PageObject.contains('span', { multiple: true })
+ * });
+ *
+ * // all spans contain 'text'
+ * assert.ok(page.spanContains('text'));
+ *
+ * @example
+ *
+ * // <div><span>lorem</span></div>
+ * // <div class="scope"><span>ipsum</span></div>
+ * // <div><span>dolor</span></div>
+ *
+ * const page = PageObject.create({
+ *   spanContains: PageObject.contains('span', { scope: '.scope' })
+ * });
+ *
+ * assert.notOk(page.spanContains('lorem'));
+ * assert.ok(page.spanContains('ipsum'));
+ *
+ * @example
+ *
+ * // <div><span>lorem</span></div>
+ * // <div class="scope"><span>ipsum</span></div>
+ * // <div><span>dolor</span></div>
+ *
+ * const page = PageObject.create({
+ *   scope: '.scope',
+
+ *   spanContains: PageObject.contains('span')
+ * });
+ *
+ * assert.notOk(page.spanContains('lorem'));
+ * assert.ok(page.spanContains('ipsum'));
+ *
+ * @public
  *
  * @param {string} selector - CSS selector of the element to check
  * @param {Object} options - Additional options
- * @param {string} options.scope - Overrides parent scope
- * @param {number} options.index - Reduce the set of matched elements to the one at the specified index
+ * @param {string} options.scope - Nests provided scope within parent's scope
+ * @param {number} options.at - Reduce the set of matched elements to the one at the specified index
+ * @param {boolean} options.resetScope - Override parent's scope
+ * @param {boolean} options.multiple - Check if all elements matched by selector contain the subtext
  * @return {Descriptor}
+ *
+ * @throws Will throw an error if no element matches selector
+ * @throws Will throw an error if multiple elements are matched by selector and multiple option is not set
  */
 export function contains(selector, options = {}) {
   return {

test-support/page-object/predicates/has-class.js

@@ -1,22 +1,84 @@
 import { findElementWithAssert, every } from '../helpers';
 
 /**
- * Creates a predicate to validate if an element has a given CSS class
+ * Validates if an element or a set of elements have a given CSS class.
  *
  * @example
  *
- *   var page = PageObject.create({
- *     isImageActive: hasClass('is-active', '.img')
- *   });
+ * // <em class="lorem"></em><span class="success">Message!</span>
  *
- *   assert.ok(page.isImageActive(), 'Image is active');
+ * const page = PageObject.create({
+ *   messageIsSuccess: PageObject.hasClass('success', 'span')
+ * });
  *
- * @param {string} cssClass - Name of the CSS class to look for
+ * assert.ok(page.messageIsSuccess);
+ *
+ * @example
+ *
+ * // <span class="success"></span>
+ * // <span class="error"></span>
+ *
+ * const page = PageObject.create({
+ *   messagesAreSuccessful: PageObject.hasClass('success', 'span', { multiple: true })
+ * });
+ *
+ * assert.notOk(page.messagesAreSuccessful);
+ *
+ * @example
+ *
+ * // <span class="success"></span>
+ * // <span class="success"></span>
+ *
+ * const page = PageObject.create({
+ *   messagesAreSuccessful: PageObject.hasClass('success', 'span', { multiple: true })
+ * });
+ *
+ * assert.ok(page.messagesAreSuccessful);
+ *
+ * @example
+ *
+ * // <div>
+ * //   <span class="lorem"></span>
+ * // </div>
+ * // <div class="scope">
+ * //   <span class="ipsum"></span>
+ * // </div>
+ *
+ * const page = PageObject.create({
+ *   spanHasClass: PageObject.hasClass('ipsum', 'span', { scope: '.scope' })
+ * });
+ *
+ * assert.ok(page.spanHasClass);
+ *
+ * @example
+ *
+ * // <div>
+ * //   <span class="lorem"></span>
+ * // </div>
+ * // <div class="scope">
+ * //   <span class="ipsum"></span>
+ * // </div>
+ *
+ * const page = PageObject.create({
+ *   scope: '.scope',
+ *   spanHasClass: PageObject.hasClass('ipsum', 'span')
+ * });
+ *
+ * assert.ok(page.spanHasClass);
+ *
+ * @public
+ *
+ * @param {string} cssClass - CSS class to be validated
  * @param {string} selector - CSS selector of the element to check
  * @param {Object} options - Additional options
- * @param {string} options.scope - Overrides parent scope
- * @param {number} options.index - Reduce the set of matched elements to the one at the specified index
+ * @param {string} options.scope - Nests provided scope within parent's scope
+ * @param {number} options.at - Reduce the set of matched elements to the one at the specified index
+ * @param {boolean} options.resetScope - Override parent's scope
+ * @param {boolean} options.multiple - Check if all elements matched by selector have the CSS class
  * @return {Descriptor}
+ *
+ * @throws Will throw an error if no element matches selector
+ * @throws Will throw an error if multiple elements are matched by selector and multiple option is not set
  */
 export function hasClass(cssClass, selector, options = {}) {
   return {