{
  "doc": {
    "id": "api/commands/contains",
    "title": "contains | Cypress Documentation",
    "description": "Get the DOM element containing the text in Cypress.",
    "section": "api",
    "source_path": "/llm/markdown/api/commands/contains.md",
    "version": "a8fd16711bdda4c7b5645b9717e588ae99ec2470",
    "updated_at": "2026-05-18T17:21:32.047Z",
    "headings": [
      {
        "id": "api/commands/contains#contains",
        "text": "contains",
        "level": 1
      },
      {
        "id": "api/commands/contains#syntax",
        "text": "Syntax",
        "level": 2
      },
      {
        "id": "api/commands/contains#usage",
        "text": "Usage",
        "level": 3
      },
      {
        "id": "api/commands/contains#arguments",
        "text": "Arguments",
        "level": 3
      },
      {
        "id": "api/commands/contains#yields-learn-about-subject-management",
        "text": "Yields Learn about subject management",
        "level": 3
      },
      {
        "id": "api/commands/contains#examples",
        "text": "Examples",
        "level": 2
      },
      {
        "id": "api/commands/contains#content",
        "text": "Content",
        "level": 3
      },
      {
        "id": "api/commands/contains#find-the-first-element-containing-some-text",
        "text": "Find the first element containing some text",
        "level": 4
      },
      {
        "id": "api/commands/contains#find-the-input-type-submit-by-value",
        "text": "Find the input[type='submit'] by value",
        "level": 4
      },
      {
        "id": "api/commands/contains#number",
        "text": "Number",
        "level": 3
      },
      {
        "id": "api/commands/contains#find-the-first-element-containing-a-number",
        "text": "Find the first element containing a number",
        "level": 4
      },
      {
        "id": "api/commands/contains#regular-expression",
        "text": "Regular Expression",
        "level": 3
      },
      {
        "id": "api/commands/contains#find-the-first-element-with-text-matching-the-regular-expression",
        "text": "Find the first element with text matching the regular expression",
        "level": 4
      },
      {
        "id": "api/commands/contains#selector",
        "text": "Selector",
        "level": 3
      },
      {
        "id": "api/commands/contains#specify-a-selector-to-return-a-specific-element",
        "text": "Specify a selector to return a specific element",
        "level": 4
      },
      {
        "id": "api/commands/contains#keep-the-form-as-the-subject",
        "text": "Keep the form as the subject",
        "level": 4
      },
      {
        "id": "api/commands/contains#case-sensitivity",
        "text": "Case Sensitivity",
        "level": 3
      },
      {
        "id": "api/commands/contains#notes",
        "text": "Notes",
        "level": 2
      },
      {
        "id": "api/commands/contains#scopes",
        "text": "Scopes",
        "level": 3
      },
      {
        "id": "api/commands/contains#when-starting-a-series-of-commands",
        "text": "When starting a series of commands:",
        "level": 4
      },
      {
        "id": "api/commands/contains#when-chained-to-an-existing-series-of-commands",
        "text": "When chained to an existing series of commands",
        "level": 4
      },
      {
        "id": "api/commands/contains#be-wary-of-chaining-multiple-contains",
        "text": "Be wary of chaining multiple contains",
        "level": 4
      },
      {
        "id": "api/commands/contains#leading-trailing-duplicate-whitespaces-arent-ignored-in-pre-tag",
        "text": "Leading, trailing, duplicate whitespaces aren't ignored in <pre> tag",
        "level": 3
      },
      {
        "id": "api/commands/contains#non-breaking-space",
        "text": "Non-breaking space",
        "level": 3
      },
      {
        "id": "api/commands/contains#single-element",
        "text": "Single Element",
        "level": 3
      },
      {
        "id": "api/commands/contains#only-the-first-matched-element-will-be-returned",
        "text": "Only the first matched element will be returned",
        "level": 4
      },
      {
        "id": "api/commands/contains#default-input-type-submit-labels",
        "text": "Default <input type=\"submit\"> labels",
        "level": 3
      },
      {
        "id": "api/commands/contains#preferences",
        "text": "Preferences",
        "level": 3
      },
      {
        "id": "api/commands/contains#element-preference-order",
        "text": "Element preference order",
        "level": 4
      },
      {
        "id": "api/commands/contains#favor-of-button-over-other-deeper-elements",
        "text": "Favor of <button> over other deeper elements",
        "level": 4
      },
      {
        "id": "api/commands/contains#favor-of-a-over-other-deeper-elements",
        "text": "Favor of <a> over other deeper elements",
        "level": 4
      },
      {
        "id": "api/commands/contains#favor-of-label-over-other-deeper-elements",
        "text": "Favor of <label> over other deeper elements",
        "level": 4
      },
      {
        "id": "api/commands/contains#rules",
        "text": "Rules",
        "level": 2
      },
      {
        "id": "api/commands/contains#requirements-learn-about-chaining-commands",
        "text": "Requirements Learn about chaining commands",
        "level": 3
      },
      {
        "id": "api/commands/contains#assertions-learn-about-assertions",
        "text": "Assertions Learn about assertions",
        "level": 3
      },
      {
        "id": "api/commands/contains#timeouts-learn-about-timeouts",
        "text": "Timeouts Learn about timeouts",
        "level": 3
      },
      {
        "id": "api/commands/contains#command-log",
        "text": "Command Log",
        "level": 2
      },
      {
        "id": "api/commands/contains#history",
        "text": "History",
        "level": 2
      },
      {
        "id": "api/commands/contains#see-also",
        "text": "See also",
        "level": 2
      }
    ]
  },
  "content": {
    "type": "root",
    "children": [
      {
        "type": "heading",
        "depth": 1,
        "children": [
          {
            "type": "text",
            "value": "contains"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Get the DOM element containing the text. DOM elements can contain more than the desired text and still match. Additionally, Cypress "
          },
          {
            "type": "link",
            "title": null,
            "url": "#Notes",
            "children": [
              {
                "type": "text",
                "value": "prefers some DOM elements"
              }
            ]
          },
          {
            "type": "text",
            "value": " over the deepest element found."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Syntax"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": ".contains(content).contains(content, options).contains(selector, content).contains(selector, content, options)// ---or---cy.contains(content)cy.contains(content, options)cy.contains(selector, content)cy.contains(selector, content, options)"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Usage"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Correct Usage"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.get('.nav').contains('About') // Yield el in .nav containing 'About'cy.contains('Hello') // Yield first el in document containing 'Hello'"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Incorrect Usage"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.title().contains('My App') // Errors, 'title' does not yield DOM elementcy.getCookies().contains('_key') // Errors, 'getCookies' does not yield DOM element"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Arguments"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "content (String, Number, RegExp)"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Get the DOM element containing the content."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "selector (String selector)"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Specify a selector to filter DOM elements containing the text. Cypress will ignore its "
          },
          {
            "type": "link",
            "title": null,
            "url": "#Notes",
            "children": [
              {
                "type": "text",
                "value": "default preference order"
              }
            ]
          },
          {
            "type": "text",
            "value": " for the specified selector. Using a selector allows you to return more shallow elements (higher in the tree) that contain the specific text."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "options (Object)"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Pass in an options object to change the default behavior of `.contains()`."
          }
        ]
      },
      {
        "type": "table",
        "align": [
          null,
          null,
          null
        ],
        "children": [
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Option"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Default"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Description"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`matchCase`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`true`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Check case sensitivity"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`log`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`true`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Displays the command in the "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/core-concepts/open-mode.md#Command-Log",
                    "children": [
                      {
                        "type": "text",
                        "value": "Command log"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`timeout`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/configuration.md#Timeouts",
                    "children": [
                      {
                        "type": "text",
                        "value": "`defaultCommandTimeout`"
                      }
                    ]
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Time to wait for `.contains()` to resolve before "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "#Timeouts",
                    "children": [
                      {
                        "type": "text",
                        "value": "timing out"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`includeShadowDom`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/configuration.md#Global",
                    "children": [
                      {
                        "type": "text",
                        "value": "`includeShadowDom` config option value"
                      }
                    ]
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Whether to traverse shadow DOM boundaries and include elements within the shadow DOM in the yielded results."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Yields "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/core-concepts/introduction-to-cypress.md#Subject-Management",
            "children": [
              {
                "type": "text",
                "value": "Learn about subject management"
              }
            ]
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`.contains()` yields the new DOM element it found."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`.contains()` is a query, and it is safe to chain further commands."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Examples"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Content"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Find the first element containing some text"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "<ul>  <li>apples</li>  <li>oranges</li>  <li>bananas</li></ul>"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// yields <li>apples</li>cy.contains('apples')"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Find the `input[type='submit']` by value"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Get the form element and search in its descendants for the content \"submit the form!\""
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "<div id=\"main\">  <form>    <div>      <label>name</label>      <input name=\"name\" />    </div>    <div>      <label>age</label>      <input name=\"age\" />    </div>    <input type=\"submit\" value=\"submit the form!\" />  </form></div>"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// yields input[type='submit'] element then clicks itcy.get('form').contains('submit the form!').click()"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Number"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Find the first element containing a number"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Even though the `<span>` is the deepest element that contains a \"4\", Cypress automatically yields `<button>` elements over spans because of its "
          },
          {
            "type": "link",
            "title": null,
            "url": "#Preferences",
            "children": [
              {
                "type": "text",
                "value": "preferred element order"
              }
            ]
          },
          {
            "type": "text",
            "value": "."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "<button class=\"btn btn-primary\" type=\"button\">  Messages <span class=\"badge\">4</span></button>"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// yields <button>cy.contains(4)"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Regular Expression"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Find the first element with text matching the regular expression"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "<ul>  <li>apples</li>  <li>oranges</li>  <li>bananas</li></ul>"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// yields <li>bananas</li>cy.contains(/^b\\w+/)"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Selector"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Specify a selector to return a specific element"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Technically the `<html>`, `<body>`, `<ul>`, and first `<li>` in the example below all contain \"apples\"."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Normally Cypress would return the first `<li>` since that is the deepest element that contains \"apples\"."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "To override the element that is yielded we can pass 'ul' as the selector."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "<html>  <body>    <ul>      <li>apples</li>      <li>oranges</li>      <li>bananas</li>    </ul>  </body></html>"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// yields <ul>...</ul>cy.contains('ul', 'apples')"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Keep the form as the subject"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Here's an example that uses the selector to ensure that the `<form>` remains the "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/core-concepts/introduction-to-cypress.md#Subject-Management",
            "children": [
              {
                "type": "text",
                "value": "subject"
              }
            ]
          },
          {
            "type": "text",
            "value": " for future chaining."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "<form>  <div>    <label>name</label>    <input name=\"name\" />  </div>  <button type=\"submit\">Proceed</button></form>"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.get('form') // yields <form>...</form>  .contains('form', 'Proceed') // yields <form>...</form>  .submit() // yields <form>...</form>"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Without the explicit selector the subject would change to be the `<button>`. Using the explicit selector ensures that chained commands will have the `<form>` as the subject."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Case Sensitivity"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Here's an example using the `matchCase` option to ignore case sensitivity."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "<div>Capital Sentence</div>"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.get('div').contains('capital sentence') // failcy.get('div').contains('capital sentence', { matchCase: false }) // pass"
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Notes"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Scopes"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "`.contains()` acts differently whether it's starting a series of commands or being chained off an existing series."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "When starting a series of commands:"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "This queries the entire `document` for the content."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.contains('Log In')"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "When chained to an existing series of commands"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "This will query inside of the `<#checkout-container>` element."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.get('#checkout-container').contains('Buy Now')"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Be wary of chaining multiple contains"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Let's imagine a scenario where you click a button to delete a user and a dialog appears asking you to confirm this deletion."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// This doesn't work as intendedcy.contains('Delete User').click().contains('Yes, Delete!').click()"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Because the second `.contains()` is chained off of a command that yielded the `<button>`, Cypress will look inside of the `<button>` for the new content."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "In other words, Cypress will look inside of the `<button>` containing \"Delete User\" for the content: \"Yes, Delete!\", which is not what we intended."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "What you want to do is call `cy` again, which automatically creates a new chain scoped to the `document`."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.contains('Delete User').click()cy.contains('Yes, Delete!').click()"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Leading, trailing, duplicate whitespaces aren't ignored in `<pre>` tag"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Unlike other tags, `<pre>` doesn't ignore leading, trailing, or duplicate whitespaces as shown below:"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "<!--Code for test--><h2>Other tags</h2><p>Hello, World !</p><h2>Pre tag</h2><pre>                 Hello,           World      !</pre>"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Rendered result:"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "To reflect this behavior, Cypress also doesn't ignore them."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// test result for above codecy.get('p').contains('Hello, World !') // passcy.get('p').contains('           Hello,          World   !') // failcy.get('pre').contains('Hello, World !') // failcy.get('pre').contains('                 Hello,           World      !') // pass"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Non-breaking space"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "You can use a space character in `cy.contains()` to match text in the HTML that uses a non-breaking space entity `&nbsp;`."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "<span>Hello&nbsp;world</span>"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// finds the span elementcy.contains('Hello world')"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Tip: read about assertions against a text with non-breaking space entities in "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/faq.md#How-do-I-get-an-elements-text-contents",
            "children": [
              {
                "type": "text",
                "value": "How do I get an element's text contents?"
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Single Element"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Only the first matched element will be returned"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "<ul id=\"header\">  <li>Welcome, Jane Lane</li></ul><div id=\"main\">  <span>These users have 10 connections with Jane Lane</span>  <ul>    <li>Jamal</li>    <li>Patricia</li>  </ul></div>"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "The below example will return the `<li>` in the `#header` since that is the first element that contains the text \"Jane Lane\"."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// yields #header licy.contains('Jane Lane')"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "If you wanted to select the `<span>` instead, you could narrow the elements yielded before the `.contains()`."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// yields <span>cy.get('#main').contains('Jane Lane')"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Default `<input type=\"submit\">` labels"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "When the `value` attribute is omitted from an `<input type=\"submit\">`, the default label is used and can be locale-dependent. "
          },
          {
            "type": "link",
            "title": null,
            "url": "https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/submit#omitting_the_value_attribute",
            "children": [
              {
                "type": "text",
                "value": "More info at MDN."
              }
            ]
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "When this happens, the `value` is an empty string, and there is no programmatic way for Cypress to filter elements by the label displayed by the user agent. This can cause unexpected failures when using `cy.contains()` with submit buttons."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "The solution in this case is to:"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": " // assert the empty string cy.get('input').should('have.value', '') // ---or--- // if possible, set the `value` attribute <input type=submit value=\"Submit\" />"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Preferences"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Element preference order"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "`.contains()` defaults to preferring elements higher in the tree when they are:"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`input[type='submit']`"
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`button`"
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`a`"
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`label`"
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Cypress will ignore this element preference order if you pass a selector argument to `.contains()`."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Favor of `<button>` over other deeper elements"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Even though the `<span>` is the deepest element that contains \"Search\", Cypress yields `<button>` elements over spans."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "<form>  <button>    <i class=\"fa fa-search\"></i>    <span>Search</span>  </button></form>"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// yields <button>cy.contains('Search').children('i').should('have.class', 'fa-search')"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Favor of `<a>` over other deeper elements"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Even though the `<span>` is the deepest element that contains \"Sign Out\", Cypress yields anchor elements over spans."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "<nav>  <a href=\"/users\">    <span>Users</span>  </a>  <a href=\"/signout\">    <span>Sign Out</span>  </a></nav>"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// yields <a>cy.get('nav').contains('Sign Out').should('have.attr', 'href', '/signout')"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Favor of `<label>` over other deeper elements"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Even though the `<span>` is the deepest element that contains \"Age\", Cypress yields `<label>` elements over `<span>`."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "<form>  <label>    <span>Name:</span>    <input name=\"name\" />  </label>  <label>    <span>Age:</span>    <input name=\"age\" />  </label></form>"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// yields labelcy.contains('Age').find('input').type('29')"
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Rules"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Requirements "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/core-concepts/introduction-to-cypress.md#Chains-of-Commands",
            "children": [
              {
                "type": "text",
                "value": "Learn about chaining commands"
              }
            ]
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`.contains()` can be chained off of `cy` or off a command that yields DOM element(s)."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Assertions "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/core-concepts/introduction-to-cypress.md#Assertions",
            "children": [
              {
                "type": "text",
                "value": "Learn about assertions"
              }
            ]
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`.contains()` will automatically "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/core-concepts/retry-ability.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "retry"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": " until the element(s) "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/core-concepts/introduction-to-cypress.md#Implicit-Assertions",
                    "children": [
                      {
                        "type": "text",
                        "value": "exist in the DOM"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": "."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`.contains()`will automatically "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/core-concepts/retry-ability.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "retry"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": " until all chained assertions have passed."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Timeouts "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/core-concepts/introduction-to-cypress.md#Timeouts",
            "children": [
              {
                "type": "text",
                "value": "Learn about timeouts"
              }
            ]
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`.contains()` can time out waiting for the element(s) to "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/core-concepts/introduction-to-cypress.md#Implicit-Assertions",
                    "children": [
                      {
                        "type": "text",
                        "value": "exist in the DOM"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": "."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`.contains()` can time out waiting for assertions you've added to pass."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Command Log"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Element contains text \"New User\""
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.get('h1').contains('New User')"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "The commands above will display in the Command Log as:"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "When clicking on the `contains` command within the command log, the console outputs the following:"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "History"
          }
        ]
      },
      {
        "type": "table",
        "align": [
          null,
          null
        ],
        "children": [
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Version"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Changes"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/changelog.md#5-2-0",
                    "children": [
                      {
                        "type": "text",
                        "value": "5.2.0"
                      }
                    ]
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Added `includeShadowDom` option."
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/changelog.md#4-0-0",
                    "children": [
                      {
                        "type": "text",
                        "value": "4.0.0"
                      }
                    ]
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Added support for option `matchCase`."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "See also"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/api/commands/get.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "`cy.get()`"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/api/commands/invoke.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "`.invoke()`"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/api/commands/within.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "`.within()`"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/core-concepts/retry-ability.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "Retry-ability"
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  },
  "token_estimate": 1883
}