Cypress Document Commands: Interacting with the Webpage's Underlying Structure

Cypress Document Commands

• cy.document(): This command provides access to the entire HTML document object. You can use it to access various aspects of the document, like:
  • Title
    .title() retrieves the current page title.
  • Cookies
    You can manage cookies using methods like .cookie(). These methods allow you to create, read, update, and clear cookies within the test.
  • Document Size
    Techniques like .width() and .height() can be used to get the document's width and height.

• Custom Commands: Cypress allows creating custom commands for reusability. You can use these commands to encapsulate document interactions for specific needs within your tests.
• cy.$(): While not strictly a document command, cy.$() acts similarly to jQuery and allows you to interact with DOM elements directly within the document.

---

Verifying Page Title

cy.visit('https://www.example.com'); // Visit a webpage

cy.document()
  .title()
  .should('eq', 'Example Domain'); // Assert the title matches "Example Domain"

Setting a Cookie

cy.visit('https://www.example.com');

cy.document()
  .cookie('myCookie', 'value') // Set a cookie named "myCookie" with value "value"
  .should('have.cookie', 'myCookie'); // Assert the cookie is set

Checking Document Height

cy.visit('https://www.example.com');

cy.document()
  .height()
  .then((height) => {
    expect(height).to.be.greaterThan(500); // Assert document height is greater than 500px
  });

Using cy.$() to Interact with an Element

cy.visit('https://www.example.com');

cy.$('button[type="submit"]').click(); // Click a button using its selector

// cypress/integration/customCommands.js
Cypress.Commands.add('login', (username, password) => {
  cy.document()
    .get('#username') // Interact with username field using document
    .type(username);

  cy.get('#password').type(password);

  cy.get('form').submit();
});

// cypress/integration/example.spec.js
cy.login('testuser', 'password123'); // Use the custom login command

---

Cypress Chainable Commands

Cypress offers a rich set of built-in commands that allow you to interact directly with DOM elements. These commands provide a more readable and maintainable approach compared to using cy.document(). Here are some commonly used ones:

• cy.type(text): Types text into an input field.
• cy.click(): Clicks on an element.
• cy.contains(text): Finds elements containing a specific text content.
• cy.get(selector): This is the workhorse for finding elements on the page. You can use various selectors like ID, class name, tag name, data attributes, etc.

Example (Using Chainable Commands)

cy.visit('https://www.example.com');

cy.get('#username').type('testuser');  // Find username field and type text
cy.get('#password').type('password123'); // Find password field and type text
cy.get('form').submit();                // Find submit button and click

Cypress Testing Library (CTL)

CTL is a popular library that integrates well with Cypress and promotes a more user-centric approach to testing. It provides higher-level commands that focus on the element's role and accessibility attributes, making your tests more robust and easier to understand.

Here are some key CTL commands for interacting with elements:

• getByText(text): Finds elements containing a specific text content.
• getByLabelText(labelText): Finds form elements based on their associated label text.
• getByRole(role, options): Finds elements based on their accessibility role (e.g., button, heading).

Example (Using CTL)

cy.visit('https://www.example.com');

cy.getByLabelText('Username').type('testuser');  // Find username field using label
cy.getByLabelText('Password').type('password123'); // Find password field using label
cy.getByRole('button', { name: /submit/i }).click(); // Find submit button with text "submit" (case-insensitive)

• Reserve cy.document() for specific scenarios where you need access to the entire document object or its properties (e.g., cookies, title).
• Use chainable commands or CTL for most common interactions with DOM elements. They offer better readability and maintainability.