StaleElementReferenceException handling in Selenium Python - Framework Patterns

Framework Mode - StaleElementReferenceException handling

Folder Structure

selenium_project/
├── src/
│   ├── pages/
│   │   └── login_page.py
│   ├── tests/
│   │   └── test_login.py
│   ├── utils/
│   │   └── wait_helpers.py
│   └── config/
│       └── config.yaml
├── requirements.txt
└── pytest.ini

Test Framework Layers

• Driver Layer: Manages WebDriver setup and teardown, handles browser sessions.
• Page Objects: Encapsulate web page elements and actions, use explicit waits and retry logic to handle stale elements.
• Tests: Test cases that use page objects to perform actions and assertions.
• Utilities: Helper functions like explicit wait wrappers and retry decorators to catch and recover from StaleElementReferenceException.
• Configuration: Environment settings, browser options, and credentials stored in config files.

Configuration Patterns

• Use config.yaml to store environment URLs, browser types, and timeouts.
• Load configuration at test startup to select browser and environment dynamically.
• Use environment variables or command-line options to override defaults.
• Keep sensitive data like credentials encrypted or in environment variables, not in code.

Test Reporting and CI/CD Integration

• Use pytest with plugins like pytest-html or allure-pytest for detailed HTML reports.
• Configure CI pipelines (GitHub Actions, Jenkins) to run tests on code push and publish reports.
• Include screenshots on failure to help diagnose stale element issues.
• Log retries and exceptions clearly in reports for StaleElementReferenceException handling visibility.

Best Practices for StaleElementReferenceException Handling

1. Use Explicit Waits: Always wait for elements to be present and visible before interacting.
2. Retry on Exception: Wrap element interactions in retry logic to recover from stale references.
3. Re-locate Elements: Avoid storing WebElement objects long-term; find elements fresh before each action.
4. Page Object Model: Encapsulate element lookups inside methods to centralize stale element handling.
5. Clear Logging: Log retries and exceptions to understand flaky behavior and improve stability.

Self Check

Where in this folder structure would you add a helper function that retries a click action when a StaleElementReferenceException occurs?

Key Result

Handle StaleElementReferenceException by using explicit waits, retry logic, and fresh element lookups within a layered Selenium Python framework.