Selenium 3 to 4 Upgrade: Step-by-Step Guide

Upgrading from Selenium 3 to Selenium 4 brings a more modern API, better W3C WebDriver compliance, and improved browser support. This guide walks you through the migration process, covering dependency changes, code adjustments, and common pitfalls.

What You’ll Need

• Your existing Selenium 3 project (source code and build files).
• A build tool like Maven, Gradle, or npm (depending on your language).
• Access to your test environment to run and verify changes.
• Basic familiarity with your project’s test structure.

Step-by-Step

1. Back up your project. Before making any changes, create a full backup or use version control (e.g., Git) so you can revert if needed.
2. Update the Selenium dependency.
   • For Java (Maven): change the selenium-java version to 4.x.x (e.g., 4.21.0) in your pom.xml.
   • For Java (Gradle): update the dependency in build.gradle.
   • For Python: run pip install selenium --upgrade.
   • For JavaScript: run npm install selenium-webdriver@latest.
   • For C#: update the NuGet package Selenium.WebDriver to 4.x.
3. Remove deprecated classes and methods. Selenium 4 removed many deprecated APIs. Common ones to replace:
   • WebDriverWait with ExpectedConditions (the old FluentWait still works, but the new Wait interface is preferred).
   • DesiredCapabilities is replaced by Options classes (e.g., ChromeOptions).
   • Actions class: build() is no longer needed; call perform() directly.
   • findElement(By.xpath()) still works, but consider using relative locators (RelativeLocator) for better readability.
4. Update driver management. Selenium 4 has built-in driver management via WebDriverManager (third-party) or you can use the Selenium Manager (bundled with Selenium 4.6+). This simplifies driver binaries – no need to manually set webdriver.chrome.driver unless you prefer.
5. Adjust for W3C WebDriver compliance. Selenium 4 uses the W3C protocol by default. Some capabilities that were non-standard (e.g., chromeOptions vs goog:chromeOptions) must be updated. Use the correct vendor-prefixed capabilities (e.g., goog:chromeOptions for Chrome).
6. Refactor window/tab handling. Selenium 4 introduces a new Window and Tab API. For example, to switch to a new tab, use driver.switchTo().newWindow() instead of the old key-sending hack.
7. Update locator strategies. If you used By.tagName() or other deprecated locators, they still work but are now part of the standard. The new RelativeLocator (with withTagName()) is available for finding elements near others.
8. Test your code. Run your test suite and fix any compilation errors or runtime exceptions. Pay attention to warnings about deprecated methods – they often indicate what to change.
9. Check for removed features. Some features like ExpectedConditions for element visibility have been moved to org.openqa.selenium.support.ui.ExpectedConditions – ensure imports are correct.
10. Update documentation and CI/CD. If you have CI pipelines, ensure they use the new driver management and any required environment variables.

Common Mistakes

• Forgetting to remove deprecated DesiredCapabilities. This often causes runtime errors because the old capabilities format is not fully supported.
• Not updating driver binaries. Selenium 4 requires newer driver versions; using old ones will fail with “session not created” errors.
• Using Actions without perform(). In Selenium 3, you often needed build().perform(); in Selenium 4, perform() is enough, but calling build() is harmless.
• Ignoring import changes. Many classes moved packages (e.g., ExpectedConditions). Update your imports to avoid NoClassDefFoundError.
• Assuming all code is compatible. Some third-party libraries (like WebDriverManager) may need updates too.

Tips

• Use the official Selenium upgrade guide (available on selenium.dev) for language-specific details.
• Run a small subset of tests first to catch major issues before running the full suite.
• Leverage Selenium Manager (built-in since 4.6) to automatically download drivers – it reduces setup friction.
• Use the --info or verbose logging to see deprecation warnings during test runs.
• If you use a framework like TestNG or JUnit, ensure your test runner is compatible with the new Selenium version.

Troubleshooting

• “Cannot find symbol” errors: Usually means you are using a class that no longer exists. Check the Selenium 4 API docs and replace with the new equivalent.
• “Session not created” exception: Driver version mismatch. Download the correct driver for your browser version, or use Selenium Manager.
• “Element not interactable” after upgrade: W3C strictness may cause this. Use explicit waits (WebDriverWait) to ensure the element is ready.
• Tests run slower: W3C protocol can be slightly slower; consider using the new relative locators to reduce lookup time.
• Browser window doesn’t maximize: In Selenium 4, use driver.manage().window().maximize() – it should work, but if not, set window size explicitly.
• If all else fails, revert to the backup and upgrade incrementally: Upgrade one module at a time, testing after each step.

Frequently Asked Questions

Q: Is Selenium 4 backwards compatible with Selenium 3?
A: Mostly yes, but some deprecated APIs were removed. You’ll need to fix those specific calls.

Q: Do I need to change my test code if I use only basic findElement and click?
A: In many cases, no. Basic operations work unchanged, but you should update dependencies and drivers.

Q: What is Selenium Manager?
A: It’s a built-in tool (since 4.6) that automatically downloads and manages driver binaries for you, eliminating manual driver setup.

Q: How do I handle browser options in Selenium 4?
A: Use the specific Options class (e.g., ChromeOptions) and set capabilities via setCapability with vendor-prefixed keys.

Q: Can I still use the old ExpectedConditions?
A: Yes, they are still available, but some are deprecated. Consider using the new Wait and FluentWait APIs.

Q: Will my existing tests run faster after upgrade?
A: Not necessarily. Performance depends on many factors; the upgrade mainly brings better standards compliance and new features.

Related

• Disney Plus Chromecast: How to Cast & Fix Issues
• AI Recruitment Tools: Match to Hiring Task
• Stuck in Built-In Administrator Account? Fix It