🚀 Welcome to MDriven Learn –  MDriven is now on Discord!  Don’t miss the latest Release Notes.
    Selenium Testing
    This page was created by Wikiadmin on 2026-07-29. Last edited by Wikiadmin on 2026-07-29.

    You can use Selenium to record and run browser-based regression and small-scale load tests against an MDriven Turnkey application.

    Purpose and scope

    Selenium tests web sites, so use this guide to test a Turnkey application in a browser. It is not specific to MDriven, but it provides one Windows 11-based setup for recording tests locally and then running them from the command line or on a Selenium Grid.

    Use Selenium IDE to create and edit a test project. Use the Selenium command-line runner when you want repeatable runs outside your normal desktop browser session. Use Selenium Grid when you need to run several browser sessions, particularly in parallel.

    Selenium Grid runs real browser containers. Parallel browser sessions consume significant CPU and memory, so this approach supports only a limited number of concurrent clients for load testing.

    Choose how to run tests

    Goal Recommended approach Result
    Record, edit, and try one test on your development machine Selenium IDE browser extension The test runs in a local browser.
    Run a saved .side project from a terminal Selenium command-line runner The runner uses the local browser unless its configuration specifies a Grid server.
    Run tests in parallel, select browsers, and retain Grid run assets Selenium command-line runner with Selenium Grid Grid schedules browser sessions and can save video and session-capability information.

    Prerequisites

    Before starting, make sure you have:

    • A running Turnkey application that the browser can reach. For local environment guidance, see HowTos:Local Installation. For MDriven Server administration, see HowTos:Configure and Maintain MDriven Server.
    • Google Chrome if you plan to use the Chrome Selenium IDE extension.
    • A local folder where you will store Selenium projects and Grid configuration files. In this guide, that folder contains the .side project, .side.yml, config.toml, and an assets directory.

    Create a test with Selenium IDE

    Selenium IDE is the quickest way to record, edit, and run a browser test without first configuring a command-line runner or Grid.

    1. Open the Chrome Web Store.
    2. Search for Selenium IDE.
    3. Add the Selenium IDE extension to Chrome.
    4. Select the Selenium IDE extension icon in the browser to open it.
    5. Create or record the test steps for your Turnkey application, then run the test from Selenium IDE to verify it.
    6. Save the Selenium project to your chosen local folder. Selenium IDE project files use the .side extension.

    For example, you might save a recorded project as MyTest.side. Keep its supporting configuration files in the same folder when you later run it from the command line.

    Install the Selenium command-line runner

    The Selenium command-line runner is selenium-side-runner. It uses Node.js.

    1. Download and install Node.js with the Windows installer from nodejs.org.
    2. Open a command prompt or PowerShell window after Node.js installation is complete.
    3. Install the runner globally:
    npm install -g selenium-side-runner
    1. Change to the folder that contains your .side project before running commands in the later sections.

    Run a project in a local browser

    Create a file named .side.yml in the same folder as the .side project. This is the default configuration file used by the command-line runner for projects in that folder unless you override it on the command line.

    To use the locally installed browser, do not include a server: entry in .side.yml. 

    capabilities:
  browserName: "chrome"

    Run the saved project from that folder: 

    selenium-side-runner .\MyTest.side

    The value of browserName is case-sensitive in this configuration. Use chrome, not Chrome.

    Prepare a Selenium Grid on Windows

    Use a Grid when you want the command-line runner to execute tests in browser containers rather than the locally installed browser.

    1. Install Windows Subsystem for Linux 2 (WSL2) as a Windows feature. See HowTos:Get Started with WSL if you need WSL guidance.
    2. Make sure virtualization (vCPU) is enabled in the machine BIOS.
    3. Install Docker Desktop.
    4. Read the SeleniumHQ docker-selenium documentation before choosing or changing a Grid topology.

    This guide uses Selenium's dynamic Docker Grid approach. It can scale browser containers up to the number of CPU cores available on the machine.

    Create the Grid configuration

    Create config.toml beside MyTest.side and .side.yml. The following shortened example maps requested browser capabilities to Selenium browser images and defines the Docker daemon URL and video image. 

    [docker]
# Configs map a Docker image to capabilities that select that image.
configs = [
    "selenium/standalone-firefox:4.16.1-20231219", '{"browserName": "firefox"}',
    "selenium/standalone-chrome:4.16.1-20231219", '{"browserName": "chrome"}',
    "selenium/standalone-edge:4.16.1-20231219", '{"browserName": "MicrosoftEdge"}'
]

# On Windows, expose the Docker Desktop daemon over TCP and use this URL.
url = "http://127.0.0.1:2375"

# Docker image used for video recording.
video-image = "selenium/video:ffmpeg-6.1-20231219"

    The capability requested by the test must match a browser mapping in config.toml. For example, a browserName value of chrome selects the Chrome mapping above.

    Start the dynamic Grid

    Create a PowerShell script named StartDynamicGrid.ps1 in the same folder. Using a script avoids problems entering the multi-line command at a prompt. 

    docker network create grid
docker run -d -p 4442-4444:4442-4444 --net grid --name selenium-hub selenium/hub:4.16.1-20231219
docker run -d --net grid -e SE_EVENT_BUS_HOST=selenium-hub `
    --shm-size="2g" `
    -e SE_EVENT_BUS_PUBLISH_PORT=4442 `
    -e SE_EVENT_BUS_SUBSCRIBE_PORT=4443 `
    -e SE_NODE_SESSION_TIMEOUT=60 `
    -e SE_ENABLE_TRACING=true `
    -e SE_OPTS="--log-level FINE" `
    -v ${PWD}/config.toml:/opt/bin/config.toml `
    -v ${PWD}/assets:/opt/selenium/assets `
    -v /var/run/docker.sock:/var/run/docker.sock `
    selenium/node-docker:4.16.1-20231219

    Run the script from the configuration folder. The commands mount config.toml into the Docker node and mount the local assets directory as the location for test-run assets.

    After the Grid starts, open the Selenium Grid UI to inspect it.

    Configure a project to use the Grid

    To send tests to the Grid rather than a local browser, add the Grid server: URL to .side.yml> and specify the browser capability. The following example requests Chrome at 1920×1080 and requests video recording: 

    capabilities:
  browserName: "chrome"
  se:recordVideo: "true"
  se:screenResolution: "1920x1080"
server: "http://localhost:4444/wd/hub"

    Keep browserName lowercase for Chrome. If video recording is enabled, Grid run output is written under assets. Each run creates a directory that can contain:

    • video.mp4, when se:recordVideo is set to "true".
    • sessionCapabilities.json, which records the settings under which the test session ran.

    Run tests from the command line

    From the folder containing .side.yml, config.toml, and the project file, run one project: 

    selenium-side-runner .\MyTest.side

    To request up to five concurrent workers, run: 

    selenium-side-runner -w 5 .\MyTest.side

    Parallel execution requires multiple tests in a Selenium IDE Test suite. The runner schedules tests in that suite concurrently, up to the worker count you specify and the capacity available on the Grid host.

    For example, if you want to exercise five concurrent executions, duplicate the test in the Selenium IDE project and add each copy to the default Test suite. Then run the project with -w 5. The Grid can start sessions only up to the machine's available resources.

    Troubleshooting checklist

    Symptom Check
    The runner opens or uses the local browser when you expected Grid execution. Confirm that .side.yml is in the current folder and includes server: "http://localhost:4444/wd/hub".
    Chrome does not match a Grid browser configuration. Use browserName: "chrome" in lowercase, and confirm that config.toml includes the Chrome mapping.
    No video appears in the output. Set se:recordVideo: "true" and inspect the run-specific folder under assets.
    The Grid cannot start browser containers. Confirm that WSL2, virtualization, and Docker Desktop are installed and that Docker Desktop exposes the daemon through the TCP endpoint configured in config.toml.
    Parallel execution does not occur. Confirm that the project has multiple tests in its Test suite and that you ran the command with -w.

    See also

    Testing a Turnkey application

    Testing a Turnkey application

    Selenium tests web sites and is therefore intended for testing a Turnkey application in a browser. The documented workflow is to create, edit, and run a script with the Selenium IDE browser extension, save the test project locally, and optionally run the saved test with the Selenium command-line runner or Selenium Grid.

    Record and save a browser test

    1. Install the Selenium IDE browser extension.
    2. Open the extension and create, edit, or run a test script.
    3. Save the test project to a local folder. Selenium test-project files use the .side extension.

    Selenium IDE can be used to create, edit, and run a script without local development-machine setup beyond the browser extension.

    Run a saved test from the command line

    The Selenium command-line runner uses Node.js. Install Node.js by using the Windows installer, then install the runner: 

    npm install -g selenium-side-runner

    In the folder containing the saved .side files, create a .side.yml file. This file is used for all .side files unless it is overridden from the command line.

    Without a server: setting, the runner uses the locally installed browser, as Selenium IDE does. With a server: setting, the runner calls a Grid server. 

    capabilities:
    browserName: "chrome"
    se:recordVideo: "true"
    se:screenResolution: "1920x1080"
server: "http://localhost:4444/wd/hub"

    The documented example states that the browser name is case-sensitive; use chrome, not Chrome.

    Run a saved test from the folder containing the test project and configuration: 

    selenium-side-runner .\MyTest.side

    For example, request five workers for parallel execution: 

    selenium-side-runner -w 5 .\MyTest.side

    Parallel execution requires multiple tests in a Selenium test suite. The source suggests duplicating tests and adding them to the default test suite so that the runner can schedule them concurrently.

    Run tests on Selenium Grid

    The documented Grid setup is a Windows-oriented example using WSL2, Docker Desktop, and SeleniumHQ docker-selenium images. The Grid example exposes its UI at http://localhost:4444/ui# and uses http://localhost:4444/wd/hub as the server value in .side.yml.

    For the complete dynamic-Grid configuration, including config.toml, Docker images, and startup commands, follow the Selenium Testing page.

    Turnkey-specific test details

    The available Selenium guidance does not document Turnkey-generated HTML, supported locators, stable element IDs, CSS classes, data attributes, ViewModel mappings, or required wait strategies. Do not represent a recorded locator or an observed rendered-browser detail as a supported Turnkey compatibility contract without product confirmation.

    See also
    Retrieved from "https://newwikicopy.mdriven.net/index.php?title=HowTos:Selenium_Testing&oldid=36697"

    © MDRIVEN. All Rights Reserved

    API Docs
    MDriven World| Portal| Blog| YouTube| StackOverflow| Facebook

    © MDRIVEN. All Rights Reserved