Use WebDriver (Chromium) for test automation

WebDriver allows developers to create automated tests that simulate user interaction. WebDriver tests and simulations differ from JavaScript unit tests in the following ways.

  • Accesses functionality and information not available to JavaScript running in browsers.
  • Simulates user events or OS-level events more accurately.
  • Manages multiple windows, tabs, and webpages in a single test session.
  • Runs multiple sessions of Microsoft Edge on a specific machine.

Relationship between WebDriver and other software

To automate Microsoft Edge with WebDriver to simulate user interaction, you need three components:

  • Microsoft Edge
  • Microsoft Edge Driver
  • A WebDriver testing framework

The functional relationship between these components is as follows.

Technology Role
WebDriver A W3C standard for a platform- and language-neutral wire protocol. This protocol allows out-of-process programs to remotely instruct the behavior of web browsers.
Microsoft Edge Driver Microsoft's implementation of the WebDriver protocol specifically for Microsoft Edge. Test authors write tests that use WebDriver commands that Microsoft Edge Driver receives. Microsoft Edge Driver is then responsible for communicating that command to the browser.
A WebDriver testing framework Test authors use a testing framework to write end-to-end tests and automate browsers. Provides a language-specific interface that translates your code into commands that Microsoft Edge Driver runs in Microsoft Edge (Chromium). WebDriver testing frameworks exist for all major platforms and languages. One such framework is Selenium.
Internet Explorer Driver An implementation of the WebDriver protocol specifically for Internet Explorer. To run legacy end-to-end tests for Internet Explorer, we recommend using Internet Explorer Driver.

The following sections describe how to get started with WebDriver for Microsoft Edge (Chromium).

Install Microsoft Edge (Chromium)

Ensure you install Microsoft Edge (Chromium). To confirm that you have Microsoft Edge (Chromium) installed, navigate to edge://settings/help, and verify that the version number is 75 or later.

Download Microsoft Edge Driver

To begin automating tests, use the following steps to ensure that the WebDriver version you install matches your browser version.

  1. Find your version of Microsoft Edge.

    1. Navigate to edge://settings/help.

      The build number for Microsoft Edge on April 15, 2021

  2. Navigate to Microsoft Edge Driver.

  3. Navigate to Get the latest version.

  4. Choose the build of channel that matches your version number of Microsoft Edge.

    The Get the latest version section on the Microsoft Edge Driver webpage

Choose a WebDriver testing framework

After downloading Microsoft Edge Driver, the last component you must download is a WebDriver testing framework. Test authors use WebDriver testing frameworks to write end-to-end tests and automate browsers. The framework provides a language-specific interface that translates your code (such as Python, Java, C#, Ruby, or JavaScript) into commands that Microsoft Edge Driver runs in Microsoft Edge (Chromium). WebDriver testing frameworks exist for all major platforms and languages.

This article provides instructions for using the Selenium framework, but you can use any library, framework, and programming language that supports WebDriver. To accomplish the same tasks using a WebDriver testing framework other than Selenium, consult the official documentation for your framework of choice.

If you are using Selenium, the Microsoft Edge team recommends Selenium 4.0.0-beta2 or later, because that version of Selenium supports Microsoft Edge (Chromium). However, you can control Microsoft Edge (Chromium) in all older versions of Selenium, including the current stable Selenium 3 release.

Important

If you previously automated or tested Microsoft Edge (Chromium) using ChromeDriver and ChromeOptions classes, your WebDriver code does not run on Microsoft Edge Version 80 or later. To solve the problem, update your tests to use the EdgeOptions class and download Microsoft Edge Driver.

Using Selenium 4

The Selenium WebDriver testing framework can be used on any platform, and is available for Java, Python, C#, Ruby, and JavaScript.

Selenium 4 has built-in support for Microsoft Edge (Chromium). To install Selenium 4, navigate to Installing Selenium libraries.

If you use Selenium 4, you don't need to use Selenium Tools for Microsoft Edge. Selenium Tools for Microsoft Edge are for Selenium 3 only. If you try to use Selenium 4 with Selenium Tools for Microsoft Edge and try to create a new EdgeDriver instance, you get the following error: System.MissingMethodException: 'Method not found: 'OpenQA.Selenium.Remote.DesiredCapabilities OpenQA.Selenium.DriverOptions.GenerateDesiredCapabilities(Boolean)'.

If you're using Selenium 4 and get this error, remove Microsoft.Edge.SeleniumTools from your project, and make sure you're using the official EdgeOptions and EdgeDriver classes from the OpenQA.Selenium.Edge namespace.

Using Selenium 3

If you already use Selenium 3, you may have existing browser tests and want to add coverage for Microsoft Edge (Chromium) without changing your version of Selenium. To use Selenium 3 to write automated tests for both Microsoft Edge (EdgeHTML) and Microsoft Edge (Chromium), install the Selenium Tools for Microsoft Edge package to use the updated driver. The EdgeDriver and EdgeDriverService classes included in the tools are fully compatible with the built-in equivalents in Selenium 4.

If you are using Selenium 3, use the following steps to add the Selenium Tools for Microsoft Edge and Selenium 3 to your project.

Add the Microsoft.Edge.SeleniumTools and Selenium.WebDriver packages to your .NET project using the NuGet CLI or Visual Studio.

Automate Microsoft Edge (Chromium) with WebDriver

To automate a browser using WebDriver, you must first start a WebDriver session using your preferred WebDriver testing framework. A session is a single running instance of a browser controlled using WebDriver commands. Start a WebDriver session to launch a new browser instance. The launched browser instance remains open until you close the WebDriver session.

The following content walks you through using Selenium to start a WebDriver session with Microsoft Edge (Chromium). You can run these examples using either Selenium 3 or 4. To use WebDriver with Selenium 3, the Selenium Tools for Microsoft Edge package must be installed.

Note

This article provides instructions for using the Selenium framework, but you can use any library, framework, and programming language that supports WebDriver. To accomplish the same tasks using another framework, consult the official documentation for your framework of choice.

Automate Microsoft Edge (Chromium)

Selenium uses the EdgeDriver class to manage a Microsoft Edge (Chromium) session. To start a session and automate Microsoft Edge (Chromium), create a new EdgeDriver object and pass it an EdgeOptions object with the UseChromium property set to true.

var options = new EdgeOptions();
options.UseChromium = true;

var driver = new EdgeDriver(options);

Note

If your IT admin has set the DeveloperToolsAvailability policy to 2, Microsoft Edge Driver is blocked from driving Microsoft Edge (Chromium), because the driver uses the Microsoft Edge DevTools. Ensure the DeveloperToolsAvailability policy is set to 0 or 1 to automate Microsoft Edge (Chromium).

Choose Specific Browser Binaries (Chromium-Only)

You can start a WebDriver session with specific Microsoft Edge (Chromium) binaries. For example, you can run tests using the Microsoft Edge preview channels such as Microsoft Edge Beta.

var options = new EdgeOptions();
options.UseChromium = true;
options.BinaryLocation = @"C:\Program Files (x86)\Microsoft\Edge Beta\Application\msedge.exe";

var driver = new EdgeDriver(options);

Customize the Microsoft Edge Driver Service

When you use the EdgeOptions class to create an EdgeDriver class instance, it creates and launches the appropriate EdgeDriverService class for either Microsoft Edge (EdgeHTML) or Microsoft Edge (Chromium).

If you want to create an EdgeDriverService, use the CreateChromiumService() method to create one configured for Microsoft Edge (Chromium). The CreateChromiumService() method is useful when you need to add customizations. For example, the following code starts verbose log output.

using (var service = EdgeDriverService.CreateChromiumService())
{
    service.UseVerboseLogging = true;

    var driver = new EdgeDriver(service);
}

Note

You do not need to provide the EdgeOptions object when you pass EdgeDriverService to the EdgeDriver instance. The EdgeDriver class uses the default options for either Microsoft Edge (EdgeHTML) or Microsoft Edge (Chromium) based on the service you provide.
However, if you want to provide both EdgeDriverService and EdgeOptions classes, ensure that both are configured for the same version of Microsoft Edge. For example, you may use a default Microsoft Edge (EdgeHTML) EdgeDriverService class and Chromium properties in the EdgeOptions class. The EdgeDriver class throws an error to prevent using different versions.

Use Chromium-Specific Options

If you set the UseChromium property to true, you can use the EdgeOptions class to access the same Chromium-specific properties and methods that are used when you automate other Chromium browsers.

var options = new EdgeOptions();
options.UseChromium = true;
options.AddArgument("headless");
options.AddArgument("disable-gpu");

Note

If the UseChromium property is set to true, you are not able to use properties and methods for Microsoft Edge (EdgeHTML).

Other WebDriver installation options

Docker

If you use Docker, run the following command to download a pre-configured image with Microsoft Edge (Chromium) and Microsoft Edge Driver pre-installed.

docker run -d -p 9515:9515 mcr.microsoft.com/msedge/msedgedriver

For more information, navigate to the msedgedriver container on Docker Hub.

Testing Internet Explorer

To test sites that require Internet Explorer, use Internet Explorer Driver with Internet Explorer. Internet Explorer Driver is maintained by the Selenium project. Even though Microsoft Edge supports IE Mode, you can't use Microsoft Edge Driver with Microsoft Edge to test sites in IE Mode.

Application Guard

Trusted sites that use Microsoft Defender Application Guard (Application Guard) can be automated using Microsoft Edge Driver.

Untrusted sites that use Application Guard cannot be automated or manipulated using Microsoft Edge Driver. Application Guard launches untrusted sites in a container, and this container doesn't expose the remote debugging port that Microsoft Edge Driver needs to communicate with the site.

Your enterprise administrator defines what are trusted sites, including cloud resources and internal networks. Sites that aren't in the trusted sites list are considered untrusted. Microsoft Edge Driver can automate both InPrivate windows, and sites in the trusted sites list.

For more information about Application Guard, navigate to:

See also

  • Selenium documentation - Information about WebDriver in the context of Selenium, and how to write automated WebDriver tests using Selenium.

Getting in touch with the Microsoft Edge DevTools team

The Microsoft Edge team is eager to hear your feedback about using WebDriver, WebDriver testing frameworks (such as Selenium), and Microsoft Edge. To send the team your questions and comments, choose the Send Feedback icon in the Microsoft Edge DevTools or send a tweet @EdgeDevTools.

The Send Feedback icon in the Microsoft Edge DevTools