locators.js 6.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216
  1. // Used to provide better protractor documentation for webdriver. These files
  2. // are not used to provide code for protractor and are only used for the website.
  3. /**
  4. * @fileoverview Factory methods for the supported locator strategies.
  5. */
  6. goog.provide('webdriver');
  7. /**
  8. * A collection of factory functions for creating {@link webdriver.Locator}
  9. * instances.
  10. */
  11. webdriver.By = {};
  12. /**
  13. * Locates elements that have a specific class name. The returned locator
  14. * is equivalent to searching for elements with the CSS selector ".clazz".
  15. *
  16. * @view
  17. * <ul class="pet">
  18. * <li class="dog">Dog</li>
  19. * <li class="cat">Cat</li>
  20. * </ul>
  21. *
  22. * @example
  23. * // Returns the web element for dog
  24. * var dog = element(by.className('dog'));
  25. * expect(dog.getText()).toBe('Dog');
  26. *
  27. * @param {string} className The class name to search for.
  28. * @returns {!webdriver.Locator} The new locator.
  29. * @see http://www.w3.org/TR/2011/WD-html5-20110525/elements.html#classes
  30. * @see http://www.w3.org/TR/CSS2/selector.html#class-html
  31. */
  32. webdriver.By.className = webdriver.Locator.factory_('class name');
  33. /**
  34. * Locates elements using a CSS selector. For browsers that do not support
  35. * CSS selectors, WebDriver implementations may return an
  36. * {@linkplain bot.Error.State.INVALID_SELECTOR invalid selector} error. An
  37. * implementation may, however, emulate the CSS selector API.
  38. *
  39. * @view
  40. * <ul class="pet">
  41. * <li class="dog">Dog</li>
  42. * <li class="cat">Cat</li>
  43. * </ul>
  44. *
  45. * @example
  46. * // Returns the web element for cat
  47. * var cat = element(by.css('.pet .cat'));
  48. * expect(cat.getText()).toBe('Cat');
  49. *
  50. * @param {string} selector The CSS selector to use.
  51. * @returns {!webdriver.Locator} The new locator.
  52. * @see http://www.w3.org/TR/CSS2/selector.html
  53. */
  54. webdriver.By.css = webdriver.Locator.factory_('css selector');
  55. /**
  56. * Locates an element by its ID.
  57. *
  58. * @view
  59. * <ul id="pet_id">
  60. * <li id="dog_id">Dog</li>
  61. * <li id="cat_id">Cat</li>
  62. * </ul>
  63. *
  64. * @example
  65. * // Returns the web element for dog
  66. * var dog = element(by.id('dog_id'));
  67. * expect(dog.getText()).toBe('Dog');
  68. *
  69. * @param {string} id The ID to search for.
  70. * @returns {!webdriver.Locator} The new locator.
  71. */
  72. webdriver.By.id = webdriver.Locator.factory_('id');
  73. /**
  74. * Locates link elements whose {@linkplain webdriver.WebElement#getText visible
  75. * text} matches the given string.
  76. *
  77. * @view
  78. * <a href="http://www.google.com">Google</a>
  79. *
  80. * @example
  81. * expect(element(by.linkText('Google')).getTagName()).toBe('a');
  82. *
  83. * @param {string} text The link text to search for.
  84. * @returns {!webdriver.Locator} The new locator.
  85. */
  86. webdriver.By.linkText = webdriver.Locator.factory_('link text');
  87. /**
  88. * Locates an elements by evaluating a JavaScript expression, which may
  89. * be either a function or a string. Like
  90. * {@link webdriver.WebDriver.executeScript}, the expression is evaluated
  91. * in the context of the page and cannot access variables from
  92. * the test file.
  93. *
  94. * The result of this expression must be an element or list of elements.
  95. *
  96. * @alias by.js(expression)
  97. * @view
  98. * <span class="small">One</span>
  99. * <span class="medium">Two</span>
  100. * <span class="large">Three</span>
  101. *
  102. * @example
  103. * var wideElement = element(by.js(function() {
  104. * var spans = document.querySelectorAll('span');
  105. * for (var i = 0; i < spans.length; ++i) {
  106. * if (spans[i].offsetWidth > 100) {
  107. * return spans[i];
  108. * }
  109. * }
  110. * }));
  111. * expect(wideElement.getText()).toEqual('Three');
  112. *
  113. * @param {!(string|Function)} script The script to execute.
  114. * @param {...*} var_args The arguments to pass to the script.
  115. * @returns {!webdriver.Locator}
  116. */
  117. webdriver.By.js = function(script, var_args) {};
  118. /**
  119. * Locates elements whose {@code name} attribute has the given value.
  120. *
  121. * @view
  122. * <ul>
  123. * <li name="dog_name">Dog</li>
  124. * <li name="cat_name">Cat</li>
  125. * </ul>
  126. *
  127. * @example
  128. * // Returns the web element for dog
  129. * var dog = element(by.name('dog_name'));
  130. * expect(dog.getText()).toBe('Dog');
  131. *
  132. * @param {string} name The name attribute to search for.
  133. * @returns {!webdriver.Locator} The new locator.
  134. */
  135. webdriver.By.name = webdriver.Locator.factory_('name');
  136. /**
  137. * Locates link elements whose {@linkplain webdriver.WebElement#getText visible
  138. * text} contains the given substring.
  139. *
  140. * @view
  141. * <ul>
  142. * <li><a href="https://en.wikipedia.org/wiki/Doge_(meme)">Doge meme</a></li>
  143. * <li>Cat</li>
  144. * </ul>
  145. *
  146. * @example
  147. * // Returns the 'a' web element for doge meme and navigate to that link
  148. * var doge = element(by.partialLinkText('Doge'));
  149. * doge.click();
  150. *
  151. * @param {string} text The substring to check for in a link's visible text.
  152. * @returns {!webdriver.Locator} The new locator.
  153. */
  154. webdriver.By.partialLinkText = webdriver.Locator.factory_(
  155. 'partial link text');
  156. /**
  157. * Locates elements with a given tag name. The returned locator is
  158. * equivalent to using the
  159. * [getElementsByTagName](https://developer.mozilla.org/en-US/docs/Web/API/Element.getElementsByTagName)
  160. * DOM function.
  161. *
  162. * @view
  163. * <a href="http://www.google.com">Google</a>
  164. *
  165. * @example
  166. * expect(element(by.tagName('a')).getText()).toBe('Google');
  167. *
  168. * @param {string} text The substring to check for in a link's visible text.
  169. * @returns {!webdriver.Locator} The new locator.
  170. * @see http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html
  171. */
  172. webdriver.By.tagName = webdriver.Locator.factory_('tag name');
  173. /**
  174. * Locates elements matching a XPath selector. Care should be taken when
  175. * using an XPath selector with a {@link webdriver.WebElement} as WebDriver
  176. * will respect the context in the specified in the selector. For example,
  177. * given the selector {@code "//div"}, WebDriver will search from the
  178. * document root regardless of whether the locator was used with a
  179. * WebElement.
  180. *
  181. * @view
  182. * <ul>
  183. * <li><a href="https://en.wikipedia.org/wiki/Doge_(meme)">Doge meme</a></li>
  184. * <li>Cat</li>
  185. * </ul>
  186. *
  187. * @example
  188. * // Returns the 'a' element for doge meme
  189. * var li = element(by.xpath('//ul/li/a'));
  190. * expect(li.getText()).toBe('Doge meme');
  191. *
  192. * @param {string} xpath The XPath selector to use.
  193. * @returns {!webdriver.Locator} The new locator.
  194. * @see http://www.w3.org/TR/xpath/
  195. */
  196. webdriver.By.xpath = webdriver.Locator.factory_('xpath');