Browser configuration and handling

This chapter covers browser handling, setting up browsers, defining their properties, and multi-browser handling.

Browser Handling

To handle and control browsers in Neodymium the following annotations are used.

• @Browser - use default browser
• @Browser("<browserId>") - set browser to use
• @RandomBrowser(<number of browsers to use>) - use random browser
• @SuppressBrowser() - suppress all browser
• @StartNewBrowserForSetUp - new fresh browser for @Before and @BeforeAll
• @StartNewBrowserForCleanUp - new fresh browser for @After and @AfterAll

For all browser tests @Browser, @Browser("<browserId>") or @RandomBrowser(<number of browsers to use>) must be added to the test class or method. Otherwise, advanced features, like test recording, doesn’t work.

On execution each @NeodymiumTest method will be automatically executed with each annotated browser configuration. Neodymium creates the browser instance according to the configuration, injects the resulting web driver in Selenide and clear them up afterwards.

@Browser("<browserId>") selects the browser to use. The <browserId> is a reference to the defined browser configurations in the config/browser.properties explained here.

Browser Configuration

Browser configurations are stored in the file config/browser.properties. Since it is a property file a special format is needed to define a configuration.

Format: browserprofile.<browserId>.<property> = <value>

• browserprofile is a static prefix that must be used for every configuration.
• <browserId> is a user defined string that is later used to be referred with @Browser("<browserId>") annotation
• <property> is one of the listed below
• <value> is the value to set

The following table lists all possible properties.

Global Browser Profile Configuration

The following properties can be configured on a global level. A specific configuration on browser profile level will override the global value.

browserprofile.global.pageLoadStrategy=normal|eager|none
browserprofile.global.headless=true|false
browserprofile.global.acceptInsecureCertificates=true|false
browserprofile.global.browserResolution=1200x900

Browser Preference Configuration

For Chrome and Firefox it’s possible to configure a list of preferences stored in config/browser.properties. The list for Chrome can be found here. For Firefox check about:config in your actual Firefox browser.

Please be aware that different browsers use different preference keys.

Set Up a Specific Browser Executable

Sometimes the browser of your choice is not configured in your system PATH and the WebDriver is not able to find it. Or you would like to test a certain browser like a developer edition or an extended service release. You need to configure the path to the browser in the config/neodymium.properties file.

e.g. neodymium.webDriver.firefox.pathToBrowser = /usr/bin/firefox

More documentation on the settings within the config/neodymium.properties can be found on the Neodymium configuration properties page.

Multi Browser Handling

Running tests with multiple browsers is fairly easy, only multiple @Browser annotations with all desired browsers need to be added to the test class or method. Thanks to the multi browser support you can execute your test with different browser configurations.

@SuppressBrowsers can be used to disable multi browser for the method or class. Be aware that @SuppressBrowsers on a class can be overridden on method scope by annotating a @Browser to a method.

@Browser("Firefox_large")
@Browser("Chrome_large")
@Browser("InternetExplorer_small")
public class MyTests
{
    @NeodymiumTest
    public void testMethod()
    {
        // implementation
    }

    @NeodymiumTest
    @SuppressBrowsers
    public void noBrowserTest()
    {
        // implementation
    }
}

The example above is annotated with three different browsers and one method is suppressing all browsers. testMethod() will be executed with all browsers while noBrowserTest() will also be executed but without any browser. This can be seen in the image below.

Multi browser test execution.

Furthermore, you can filter which browser should be used for testing with the property neodymium.webDriver.browserFilter. This property allows you to provide a list of specific browsers to use for your tests. As a result, only tests that are explicitly annotated for a particular browser will be executed with that browser. For the example above neodymium.webDriver.browserFilter = Firefox_large, Chrome_large, would only execute the test with Firefox and Chrome. If you take the example above, and you were to set the property to neodymium.webDriver.browserFilter = Firefox_large, Chrome_large, the test would only run on Firefox and Chrome. The Internet Explorer would be ignored.

The browser filter can also be passed via the Maven command line using -Dneodymium.webDriver.browserFilter=Firefox_large or the shorter -Dbrowserdefinition=Firefox_large.

Separate Browser Sessions for Test Setup and Cleanup

This feature allows you to manage separate browser instances for test setup (@Before/@BeforeEach) and cleanup ( @After/@AfterEach) methods using dedicated annotations. This is particularly useful when a proper clean up is essential for your testing or when you need to start testing after the setup in a clean session.

Background

An unsolved problem for each test automation are crashing browser instances. It happens rarely, nowadays but it does and when it does everything which should happen after the browser is closed can’t be done. To ensure a proper cleanup of your test system, Neodymium offers a way to use separate browsers with a clean session to perform setup and cleanup tasks.

Annotations

@StartNewBrowserForSetUp

Indicates that a new browser instance should be created specifically for the @Before method execution.

@StartNewBrowserForSetUp
@BeforeEach
public void setUp()
{
    // This will run in a separate browser instance
    // Browser will be automatically closed after setup
}

@StartNewBrowserForCleanUp

Indicates that a new browser instance should be created specifically for the @After method execution.

@StartNewBrowserForCleanUp
@AfterEach
public void cleanUp()
{
    // This will run in a separate browser instance
    // Browser will be automatically closed after cleanup
}

Usage Examples

Here is a small example how to use the annotations for separate browser sessions.

public class TestExample
{
    @StartNewBrowserForSetUp
    @BeforeEach
    public void prepareTestData()
    {
        // Setup complex test data
        open("http://admin.example.com");
        // Create necessary test data
    }

    @NeodymiumTest
    public void testUserFlow()
    {
        // Test runs in its own browser instance
        open("http://example.com");
        // Test user flow
    }

    @StartNewBrowserForCleanUp
    @AfterEach
    public void removeTestData()
    {
        // Clean up in separate browser
        open("http://admin.example.com");
        // Remove test data
    }
}

This feature supports JUnit4 as well as JUnit5. The examples above can be easily transferred to JUnit4 by changing from @BeforeEach to @Before and @AfterEach to @After.

Important Notes

1. Browser Lifecycle
   • Each annotated method receives a fresh browser instance
   • Browser instances are automatically closed after method execution
2. Best Practices
   • Use separate browsers when setup/cleanup requires different user sessions or the additional safety net for browser crashes.
   • Consider performance implications of creating multiple browser instances
   • Ensure proper error handling in setup and cleanup methods
3. Limitations
   • @BeforeAll and @AfterAll (or JUnit4s @BeforeClass and @AfterClass) are NOT covered with this, due to the general Neodymium lifecycle.
   • Browser state is not shared between different instances
   • Each new browser instance requires additional system resources, but there are no browsers running in parallel
   • Setup time may increase due to multiple browser launches