Login

How to Scroll in a Flutter Web App Using Cypress

November 17, 2024
5 minutes
Cypress
Share
51 Views
How to Scroll in a Flutter Web App Using Cypress

Scrolling in a web application is a common requirement during automated testing, especially when elements are dynamically loaded or hidden within scrollable containers. This guide focuses on how to scroll in a Flutter web app using Cypress, leveraging a custom Cypress command and implementing detailed logic to ensure your target elements are scrolled into view effectively. Whether you are testing a dynamic user interface or verifying accessibility, mastering this technique will enhance your Cypress testing workflow.

how-scroll-up-and-down-in-cypress-flutter-web-app
How To Scroll In Flutter Web Using Cypress

Why Scrolling Matters in Flutter Web Apps

Flutter web apps often utilize custom or non-standard scrolling implementations due to their framework-specific rendering. Identifying and interacting with elements hidden within scrollable areas requires more than default Cypress commands. With Cypress’s flexibility and a custom command, we can efficiently scroll through content until the desired element is visible. In this guide, you’ll learn step-by-step how to scroll in a Flutter web app using Cypress and apply it to test scenarios.

Identify the Scrollable Container

To start, open your Flutter web app in Google Chrome.

google-chrome0find-flutter-scrollable-element
Google Chrome: Inspecting Scrollable Element in Flutter Web
  • Right-click anywhere on the page and select Inspect to launch Chrome DevTools.
  • Once DevTools is open, press Command + F (or Ctrl + F on Windows) to activate the search bar.
  • In the search bar, type overflow-y: scroll to locate elements with scrollable containers in the DOM.

Navigate through the DOM structure to identify the specific scrollable container relevant to your app. In Flutter web apps, scrollable elements typically feature styles such as:

Find Scrollable Element
[style*="position: absolute; touch-action: none; overflow-y: scroll;"]

Custom Cypress Scroll Down Command

To enable efficient scrolling, we will define a Cypress command, scrollDownUntilVisible, which repeatedly scrolls through a container until the target element becomes visible. Below is the code for the custom command:

Custom: scrollDownUntilVisible function
Cypress.Commands.add('scrollDownUntilVisible', (selector, maxScrolls = 15) => {
  let scrollCount = 0;

  function scrollAndCheck() {
    if (scrollCount >= maxScrolls) {
      throw new Error
      (`Element with selector '${selector}' not visible after ${maxScrolls} scroll attempts.`);
    }

    // Get the scrollable container
    cy.get('[style*="position: absolute; touch-action: none; overflow-y: scroll;"]').then(($scrollable) => 
     {
      if ($scrollable.length === 0) {
        throw new Error('Scrollable container not found.');
      }

      const scrollableElement = $scrollable[0];
      scrollableElement.scrollTop += 1.2; // Increment scroll position

      cy.wait(500).then(() => {
        scrollCount += 1;

        // Use Cypress.$ to check if the element exists in the DOM
        const $target = Cypress.$(selector);

        if ($target.length > 0 && $target.is(':visible')) {
          // Element is found and visible
          cy.get(selector).scrollIntoView({ easing: 'linear' });
        } else {
          // Element not yet visible, continue scrolling
          scrollAndCheck();
        }
      });
    });
  }

  scrollAndCheck();
});

Understanding the Scroll Down Logic

  1. Selector Targeting: The custom command scrolls within a container identified by specific styles (overflow-y: scroll) to ensure compatibility with Flutter's rendering.
  2. Scroll Iteration: The function scrolls incrementally by adjusting the container's scrollTop property, checking the visibility of the target element after each scroll.
  3. Error Handling: If the maximum number of scroll attempts is reached, an error is thrown to indicate the element could not be found, ensuring clear debugging feedback.
  4. Smooth Interaction: The scrollIntoView method ensures the target element is properly aligned within the viewport.

Adding Scroll Up Functionality

While scrolling down in a Flutter web app is crucial for navigating and interacting with elements, there are many scenarios where scrolling back to the top is just as important. For example, ensuring key UI elements like navigation menus or icons (e.g., a login icon) are visible at the top of the page after interactions lower on the page. This section will teach you how to implement and use a Cypress command for scrolling up in a Flutter web app.

Below is the scrollUpToTop custom command, which ensures the application scrolls up to the top of a container. It halts when the desired top-most element, such as the login icon, is visible or the scrollable area has reached its limit.

Custom: scrollUpToTop function
Cypress.Commands.add('scrollUpToTop', (maxScrolls = 15) => {
  let scrollCount = 0;

  function scrollUp() {
    cy.get('[style*="position: absolute; touch-action: none; overflow-y: scroll;"]')
      .then(($scrollable) => {
        // Ensure the scrollable element exists
        if ($scrollable.length === 0) {
          throw new Error(`Scrollable element not found.`);
        }
        const scrollableElement = $scrollable[0];
        // Stop scrolling if the login icon is visible
        cy.get('[aria-label="login-icon"]').then(($loginIcon) => {
          if ($loginIcon.is(':visible')) {
            cy.log('Scrolled to the top successfully. "login-icon" is visible.');
            return;
          }
          // Stop if already at the top
          if (scrollableElement.scrollTop === 0) {
            cy.log('Scrolled to the top successfully.');
            return;
          }
          // Check scroll limit
          if (scrollCount >= maxScrolls) {
            throw new Error(`Failed to scroll up to the top after ${maxScrolls} attempts.`);
          }
          // Scroll up by decreasing the scrollTop value
          scrollableElement.scrollTop = Math.max(0, scrollableElement.scrollTop - 100);
          scrollCount += 1;
          // Wait for the scroll to settle and then check again
          cy.wait(500).then(() => {
            scrollUp();
          });
        });
      });
  }
  scrollUp();
});

How the Scroll-Up Command Works

  1. Scrollable Container Identification: The command locates the scrollable container using a CSS style selector ([style*="position: absolute; touch-action: none; overflow-y: scroll;"]), tailored to Flutter web apps.
  2. Stop Conditions: a) The login-icon (or another top element) becomes visible. b) The container reaches the top (scrollTop === 0).
  3. Iteration Control: The scroll operation runs incrementally, reducing the scrollTop value by 100 pixels per iteration until the target condition is met or the maximum number of scroll attempts is reached.
  4. Error Handling: If the top cannot be reached within the maxScrolls attempts, the command throws an error for better debugging.
  5. Wait for Smooth Operation: A small delay (cy.wait(500)) is introduced to simulate natural scrolling and allow UI updates to settle.

Cypress Test Case for Scrolling

Here’s how you can use the scrollDownUntilVisible command in a practical test scenario:

Test: Scrolling Down Page
Test: Scroll Down The Page
scrollDownUntilVisible in Use
describe('Accessories Section', () => {
    before(() => {
    // This will run before each test, ensuring the website is always launched with custom viewport
    cy.viewport(1500, 780);
    cy.visit('/');
    cy.wait(3000);
    cy.get('.lds-roller', { timeout: 15000 }).should('not.be.visible');
    cy.get('.lds-roller').invoke('css', 'display', 'none');
  });
    
    it('verify that the elements are displayed and scroll back up', () => {
      cy.wait(2000)
      // Perform actions that may scroll down the page
      cy.scrollDownUntilVisible('flt-semantics[aria-label="New arrivals"]');
      cy.get('flt-semantics[aria-label="New arrivals"]').should('be.visible');
    });
  });

Explanation of the Test

  1. Target Element: The test focuses on identifying specific elements, such as "Volleyball" and "Accessories," ensuring they are visible after scrolling.
  2. Dynamic Assertions: Multiple assertions verify that all elements in a section are present and displayed correctly, catering to Flutter’s semantic labels.
  3. Sequential Steps: The test proceeds logically, scrolling to make elements visible and then verifying their presence and functionality.

Cypress Test Case Using scrollUpToTop

Here is an example of how to incorporate the scrollUpToTop command in a Cypress test case to verify UI functionality at the top of the scrollable container.

Test: Scrolling Down Page
Test: Scrolling Down Page
scrollUpToTop In Use
describe('Accessories Section', () => {
    before(() => {
    // This will run before each test, ensuring the website is always launched with custom viewport
    cy.viewport(1500, 780);
    cy.visit('/');
    cy.wait(3000);
    cy.get('.lds-roller', { timeout: 15000 }).should('not.be.visible');
    cy.get('.lds-roller').invoke('css', 'display', 'none');
  });
    
    it('verify that the elements are displayed and scroll back up', () => {
      cy.wait(2000)
      // Perform actions that may scroll down the page
      cy.scrollDownUntilVisible('flt-semantics[aria-label="New arrivals"]');
      cy.get('flt-semantics[aria-label="New arrivals"]').should('be.visible');
        // Scroll back up to the top
      cy.scrollUpToTop();
      cy.get('flt-semantics[aria-label="login-icon"]').should('be.visible');
    });
  });

Key Scenarios for Scroll-Up Functionality

  1. Verifying Header Visibility: After interacting with elements further down the page, check if top-level navigation or header elements reappear.
  2. Testing Back-to-Top Buttons: Ensure that "Back to Top" functionality correctly scrolls up to the beginning of a scrollable container.
  3. Accessibility Testing: Confirm that users can navigate back to key interactive elements without requiring excessive scrolling.

Conclusion

Testing Flutter web apps often requires tackling unique challenges, such as custom scrolling behaviors. By defining a tailored Cypress command, you can ensure your automation tests effectively interact with dynamically loaded content. This guide has demonstrated how to scroll in a Flutter web app using Cypress, combining robust logic, clear examples, and actionable tips. With this knowledge, you can confidently handle scroll-based scenarios in your Flutter web testing suite. By mastering these techniques, your Cypress tests will become more efficient and reliable, saving time and enhancing the quality of your applications.

Tags :

Leave a Comment

Review Your Cart
0
Add Coupon Code
Subtotal
Total Installment Payments
Bundle Discount
Checkout