mirror/cypress
1
0
Fork 0
mirror of https://github.com/cypress-io/cypress.git synced 2026-05-21 23:59:33 -05:00
Code Issues Packages Projects Releases Wiki Activity

docs: Update contains to new format

Browse Source 
- moved descriptions out of code comments and into paragraphs
- changed all double quotes in code to single quotes
This commit is contained in:
Jennifer Mann
2017-05-23 13:34:10 -04:00
parent 1e7f1c74ef
commit 68f902a334
1 changed files with 135 additions and 139 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/api/commands/contains.md
+135 -139
View File
@@ -4,51 +4,52 @@ comments: true
description: ''
---
Get the DOM element containing the text. DOM elements can contain *more* than the desired text and still match. Additionally, Cypress will prefer some DOM elements over the deepest element found.
Get the DOM element containing the text. DOM elements can contain *more* than the desired text and still match. Additionally, Cypress will [prefer some DOM elements](#notes) over the deepest element found.
**Preference order:**
# Syntax
- `input[type='submit']`
- `button`
- `a`
- `label`
```javascript
cy.contains(content)
cy.contains(selector, content)
cy.contains(selector, content, options)
```
| | |
|--- | --- |
| **Returns** | the deepest DOM element containing the text |
| **Timeout** | `cy.contains` will retry for the duration of the [`defaultCommandTimeout`](https://on.cypress.io/guides/configuration#timeouts) |
## Parameters
# [cy.contains( *text* )](#text-usage)
**content**
Get the deepest DOM element containing the text.
Get the deepest DOM element containing the content. Content can be a:
# [cy.contains( *number* )](#number-usage)
- *string*
- *number*
- *regular expression*
Get the deepest DOM element containing the number.
**selector**
# [cy.contains( *regexp* )](#regular-expression-usage)
Specify a selector to filter DOM elements containing the text. Cypress will *ignore* it's [default preference order](#notes) for the specified selector. Using a selector allows you to return more *shallow* elements in the tree which contain the specific text.
Get the deepest DOM element containing the text matching the regular expression.
# [cy.contains( *selector*, *text* )](#selector-and-text-usage)
Specify a selector to filter DOM elements containing the text. Cypress will **ignore** it's default preference for the specified selector. Using a selector allows you to return more *shallow* elements in the tree which contain the specific text.
# Options
**options**
Pass in an options object to change the default behavior of `cy.contains`.
**cy.contains( *text*, *options* )**
**cy.contains( *selector*, *text*, *options* )**
Option | Default | Notes
--- | --- | ---
`log` | `true` | whether to display command in command log
`timeout` | [`defaultCommandTimeout`](https://on.cypress.io/guides/configuration#timeouts) | Total time to retry finding an element
`timeout` | [`defaultCommandTimeout`](https://on.cypress.io/guides/configuration#timeouts) | Total time to retry finding an element containing the content
# Text Usage
## Yields
## Find the first element containing some text
`cy.contains()` yields the *first*, *deepest* DOM element containing the text.
## Timeout
`cy.contains()` will try to find the content within the DOM for the duration of the [`defaultCommandTimeout`](https://on.cypress.io/guides/configuration#timeouts)
# Examples
## String Content
**Find the first element containing some text**
```html
<ul>
@@ -59,11 +60,13 @@ Option | Default | Notes
```
```javascript
// returns <li>apples</li>
cy.contains("apples")
// yields <li>apples</li>
cy.contains('apples')
```
## Find the input[type='submit'] by value
**Find the input[type='submit'] by value**
Get the form element and search in its descendants for the content "submit the form!"
```html
<div id="main">
@@ -82,14 +85,13 @@ cy.contains("apples")
```
```javascript
// get the form element
// search inside its descendants for the content 'submit the form!'
// find the input[type='submit'] element
// click it
cy.get("form").contains("submit the form!").click()
// yields input[type='submit'] element then clicks it
cy.get('form').contains('submit the form!').click()
```
## Favor of `button` over other deeper elements
**Favor of `button` over other deeper elements**
Even though the `<span>` is the deepest element that contains "Search", Cypress will yield `button` elements over spans.
```html
<form>
@@ -101,21 +103,16 @@ cy.get("form").contains("submit the form!").click()
```
```javascript
// even though the <span> is the deepest element that contains: "Search"
// Cypress will automatically favor button elements higher in the chain
// in this case the <button> is returned which is why we can now drill
// into its children
cy.contains("Search").children("i").should("have.class", "fa-search")
// yields <button>
cy.contains('Search').children('i').should('have.class', 'fa-search')
```
## Favor of `a` over other deeper elements
**Favor of `a` over other deeper elements**
Even though the `<span>` is the deepest element that contains "Sign Out", Cypress will yield anchor elements over spans.
```html
<nav>
<a href="/dashboard">
<span>Dashboard</span>
</a>
<a href="/users">
<span>Users</span>
</a>
@@ -126,14 +123,15 @@ cy.contains("Search").children("i").should("have.class", "fa-search")
```
```javascript
// even though the <span> is the deepest element that contains: "Sign Out"
// Cypress will automatically favor anchor elements higher in the chain
// in this case we can assert on the anchors properties
cy.get("nav").contains("Sign Out").should("have.attr", "href", "/signout")
// yields <a>
cy.get('nav').contains('Sign Out').should('have.attr', 'href', '/signout')
```
## Favor of `label` over other deeper elements
**Favor of `label` over other deeper elements**
Even though the `<span>` is the deepest element that contains "Age", Cypress will yield `label` elements over `span`.
Additionally we don't need to look for content "Age:" omit as long as the element at least contains the text "Age", it will be yielded.
```html
<form>
@@ -149,16 +147,11 @@ cy.get("nav").contains("Sign Out").should("have.attr", "href", "/signout")
```
```javascript
// even though the <span> is the deepest element that contains: "Age"
// Cypress will favor label elements higher in the chain
// additionally we can omit the colon as long as the element
// at least contains the text 'Age'
cy.contains("Age").find("input").type("29")
// yields label
cy.contains('Age').find('input').type('29')
```
## Only the *first* matched element will be returned
**Only the *first* matched element will be returned**
```html
<ul id="header">
@@ -167,28 +160,31 @@ cy.contains("Age").find("input").type("29")
<div id="main">
<span>These users have 10 connections with Jane Lane</span>
<ul>
<li>User 1</li>
<li>User 2</li>
<li>User 3</li>
<li>Jamal</li>
<li>Patricia</li>
</ul>
</div>
```
The below example will return the `<li>` in the `#header` since that is the *first* element that contains the text "Jane Lane".
```javascript
// this will return the <li> in the #header since that is the first
// element that contains the text "Jane Lane"
cy.contains("Jane Lane")
// if you want to select the <span> inside of #main instead
// you need to scope the contains first
//now the <span> is returned
cy.get("#main").contains("Jane Lane")
// yields #header li
cy.contains('Jane Lane')
```
# Number Usage
If you wanted to select the `<span>` instead, you could narrow the elements yielded before the `.contains()`.
## Find the first element containing some number
```javascript
// yields <span>
cy.get('#main').contains('Jane Lane')
```
## Number Content
**Find the first element containing some number**
Even though the `<span>` is the deepest element that contains a "4", Cypress will automatically yield `button` elements higher in the chain
```html
<button class="btn btn-primary" type="button">
@@ -197,16 +193,13 @@ cy.get("#main").contains("Jane Lane")
```
```javascript
// even though the <span> is the deepest element that contains: 4
// Cypress will automatically favor button elements higher in the chain
// in this case the <button> is returned
// yields <button>
cy.contains(4)
```
# Regular Expression Usage
## Regular Expression Content
## Find the first element with text matching the regular expression
**Find the first element with text matching the regular expression**
```html
<ul>
@@ -217,13 +210,19 @@ cy.contains(4)
```
```javascript
// <li>bananas</li> is returned
// yields <li>bananas</li>
cy.contains(/^b\w+/)
```
# Selector and Text Usage
## Selector
## Specify a selector to return a specific element
**Specify a selector to return a specific element**
Technically the `<html>`, `<body>`, `<ul>`, and first `<li>` in the example below all contain "apples".
Normally Cypress would return the first `<li>` since that is the *deepest* element that contains: "apples"
To override the element that is yielded, we can pass `ul` as the selector.
```html
<html>
@@ -238,95 +237,92 @@ cy.contains(/^b\w+/)
```
```javascript
// technically the <html>, <body>, <ul>, and first <li> all contain "apples"
// normally Cypress would return the first <li> since that is the deepest
// element that contains: "apples"
// to override this behavior, pass a 'ul' selector
// this returns the ul element since it also contains the text
// returns <ul>...</ul>
cy.contains("ul", "apples")
// yields <ul>...</ul>
cy.contains('ul', 'apples')
```
# Notes
## Dual command can be either parent or child
**Element preference order**
- `input[type='submit']`
- `button`
- `a`
- `label`
**Dual command can be either parent or child**
`cy.contains` is a dual command. This means it can act as both a `parent` and a `child` command. Read more about [issuing commands](https://on.cypress.io/guides/issuing-commands) if this is unfamiliar.
Because it is a dual command it can either *begin* a chain of commands or work off of an *existing* subject.
**Start a chain of commands**
***Start a chain of commands***
Search for the content within the `document`.
```javascript
// search from the root scope (default: document)
cy.contains("some content")
cy.contains('some content')
```
**Find content within an existing scope**
***Find content within an existing scope***
Search within an existing subject for the content. `.contains()` will be scoped to the `<aside>` element and will only search it's DOM descendants for the content.
```javascript
// search within an existing subject for the content
// contains is now scoped to the <aside> element and will
// only search its DOM descendants for the content
cy.get("#main").find("aside").contains("Add a user")
cy.get('#main').find('aside').contains('Add a user')
```
**Be wary of chaining multiple contains**
***Be wary of chaining multiple contains***
Let's imagine a scenario where you click button to delete a user and a dialog appears asking you to confirm this deletion.
The following will not work:
```javascript
// let's imagine a scenario where you click a user's delete button
// and a dialog appears asking you to confirm this deletion.
// the following will not work:
cy
.contains("Delete User").click()
// because this is chained off of the existing button subject
// Cypress will look inside of the existing button subject
// for the new content
// in other words Cypress will look inside of the element
// containing "Delete User" for the content: "Yes I'm sure!"
.contains("Yes, I'm sure!").click()
.contains('Delete User').click()
.contains('Yes, Delete!').click()
```
**End previous chains to get back to the root scope**
Because the second `.contains()` is chained off of the existing button subject, Cypress will look inside of the existing button subject for the new content.
In other words, Cypress will look inside of the button containing "Delete User" for the content: "Yes, Delete!"
***End previous chains to get back to the root scope***
If you explicitly [`.end()`](https://on.cypress.io/api/end) the previous chain, Cypress within the `document` for the content.
```javascript
cy
// explicitly .end() the previous chain
.contains("Delete User").click().end()
// Cypress will now search the root scope
// for this content (default: document)
.contains("Yes, I'm sure!").click()
.contains('Delete User').click().end()
.contains('Yes, Delete!').click()
```
```javascript
// alternatively just call cy again which
// automatically creates a new chain from the root scope
cy.contains("Delete User").click()
cy.contains("Yes I'm sure!").click()
```
Alternatively, you could call `cy` again which automatically creates a new chain from the `document`.
```javascript
cy.contains('Delete User').click()
cy.contains('Yes, Delete!').click()
```
You could also chain the second contains off of a parent command (such as [`.get()`](https://on.cypress.io/api/get). This automatically changes the subject to `#dialog` which contains the content we're looking for.
```javascript
// you can also do this
cy
.contains("Delete User").click()
// by using the parent command .get() we automatically
// abort previous chains and change the scope to #dialog
// which contains the content we're looking for
.get("#dialog").contains("Yes I'm sure!").click()
.contains('Delete User').click()
.get('#dialog').contains('Yes, Delete!').click()
```
# Command Log
## Element contains text "New User"
**Element contains text "New User"**
```javascript
cy.get('h1').contains('New User')
```
The commands above will display in the command log as:
<img width="536" alt="screen shot 2015-11-27 at 1 43 22 pm" src="https://cloud.githubusercontent.com/assets/1271364/11446973/009ac32c-950d-11e5-9eaa-09f8b8ddf086.png">
@@ -334,7 +330,7 @@ When clicking on the `contains` command within the command log, the console outp
<img width="477" alt="screen shot 2015-11-27 at 1 43 50 pm" src="https://cloud.githubusercontent.com/assets/1271364/11446977/04b31be4-950d-11e5-811e-4fd83d364d00.png">
# Related
# See also
- [get](https://on.cypress.io/api/get)
- [within](https://on.cypress.io/api/within)