Selenium .NET Driver Lifecycles for Parallel NUnit Fixtures

Parallel NUnit fixtures are safe only when fixture instance lifetime and WebDriver lifetime agree. A private IWebDriver field looks encapsulated, yet it is still shared if NUnit runs several test methods against one fixture instance. The correct design starts by choosing a lifecycle, then selecting a parallel scope that cannot create two owners for the same field.

Use a fresh driver in [SetUp] and release it in [TearDown] for the default path. Pair that with an instance-per-test-case fixture lifecycle when child tests may run concurrently. Keep fixture-scoped reuse as an explicit, serialized exception with a guarded [OneTimeTearDown].

Separate Fixture Scope From Worker Scheduling

NUnit parallelism describes which work items may execute concurrently. It does not promise that a named worker thread is a stable resource container, and ThreadLocal<IWebDriver> does not make fixture state easier to reason about. The fixture instance and its callbacks are the useful ownership boundary.

The Selenium .NET API exposes browser drivers through IWebDriver, but the interface cannot decide whether its implementing session belongs to a test, fixture, or assembly. That policy belongs in NUnit configuration. Write it so a reviewer can answer, from attributes and callbacks alone, how many tests can touch one driver.

The diagram includes the fixture-reuse ending because that is where OneTimeTearDown belongs. For the recommended per-test lifecycle, the same flow ends in ordinary [TearDown] after every case.

Centralize Browser Construction Behind DriverOptions

Use Selenium's concrete option classes to configure the selected browser, then pass them through the common DriverOptions base only after browser-specific settings are complete. Avoid dictionaries of unvalidated capability names in test methods.

using OpenQA.Selenium;
using OpenQA.Selenium.Chrome;
using OpenQA.Selenium.Firefox;
using OpenQA.Selenium.Remote;

public enum BrowserKind
{
    Chrome,
    Firefox
}

public static class DriverFactory
{
    public static IWebDriver Create(BrowserKind browser, Uri? gridUri)
    {
        DriverOptions options = browser switch
        {
            BrowserKind.Chrome => ChromeOptions(),
            BrowserKind.Firefox => FirefoxOptions(),
            _ => throw new ArgumentOutOfRangeException(nameof(browser))
        };

        if (gridUri is not null)
        {
            return new RemoteWebDriver(gridUri, options);
        }

        return browser switch
        {
            BrowserKind.Chrome => new ChromeDriver((ChromeOptions)options),
            BrowserKind.Firefox => new FirefoxDriver((FirefoxOptions)options),
            _ => throw new ArgumentOutOfRangeException(nameof(browser))
        };
    }

    private static ChromeOptions ChromeOptions()
    {
        var options = new ChromeOptions();
        options.AddArgument("--headless");
        options.AddArgument("--lang=en-US");
        return options;
    }

    private static FirefoxOptions FirefoxOptions()
    {
        var options = new FirefoxOptions();
        options.AddArgument("-headless");
        options.SetPreference("intl.accept_languages", "en-US");
        return options;
    }
}

The local branch casts only after the same switch constructed the concrete type. A larger framework can avoid even those casts with separate typed factories, but do not add layers unless the browser matrix or configuration policy needs them.

Prefer an Instance Per Test Case

When NUnit may run test cases from one fixture concurrently, give each case its own fixture instance. Then an instance field has one logical owner, [SetUp] creates its driver, and [TearDown] releases it. This directly supports Selenium's fresh-browser-per-test guidance.

using NUnit.Framework;
using NUnit.Framework.Interfaces;
using OpenQA.Selenium;

[TestFixture(BrowserKind.Chrome)]
[TestFixture(BrowserKind.Firefox)]
[Parallelizable(ParallelScope.All)]
[FixtureLifeCycle(LifeCycle.InstancePerTestCase)]
public sealed class SearchTests
{
    private readonly BrowserKind _browser;
    private IWebDriver? _driver;

    public SearchTests(BrowserKind browser)
    {
        _browser = browser;
    }

    private IWebDriver Driver => _driver
        ?? throw new InvalidOperationException("Driver is outside its test lifecycle");

    [SetUp]
    public void StartBrowser()
    {
        var rawGridUrl = Environment.GetEnvironmentVariable("SELENIUM_GRID_URL");
        var gridUri = string.IsNullOrWhiteSpace(rawGridUrl) ? null : new Uri(rawGridUrl);
        _driver = DriverFactory.Create(_browser, gridUri);
    }

    [Test]
    public void DocumentationHasAWebDriverLink()
    {
        Driver.Navigate().GoToUrl("https://www.selenium.dev/documentation/");
        Assert.That(Driver.FindElement(By.LinkText("WebDriver")).Displayed, Is.True);
    }

    [TearDown]
    public void StopBrowser()
    {
        IWebDriver? owned = Interlocked.Exchange(ref _driver, null);
        if (owned is null) return;

        try
        {
            if (TestContext.CurrentContext.Result.Outcome.Status == TestStatus.Failed)
            {
                CaptureFailure(owned);
            }
        }
        catch (Exception captureError)
        {
            TestContext.Error.WriteLine($"Artifact capture failed: {captureError}");
        }
        finally
        {
            try
            {
                owned.Quit();
            }
            finally
            {
                owned.Dispose();
            }
        }
    }

    private static void CaptureFailure(IWebDriver driver)
    {
        if (driver is not ITakesScreenshot camera) return;
        string safeId = string.Concat(
            TestContext.CurrentContext.Test.ID.Select(
                character => char.IsLetterOrDigit(character) ? character : '_'));
        string directory = Path.Combine(TestContext.CurrentContext.WorkDirectory, "artifacts");
        Directory.CreateDirectory(directory);
        File.WriteAllBytes(
            Path.Combine(directory, $"{safeId}.png"),
            camera.GetScreenshot().AsByteArray);
    }
}

If StartBrowser throws before assigning _driver, teardown sees null. If later setup work is added after assignment and fails, teardown still owns the session. Interlocked.Exchange makes release idempotent and prevents helper teardown paths from acting on an already-released field.

Preserve the Primary Failure During Cleanup

Artifact capture, Quit, and Dispose can each fail independently. Keep capture inside its own guarded block so it cannot bypass session release. Record cleanup exceptions with the test result, but avoid replacing the original assertion with only a screenshot or teardown error.

Capture before Quit; after the remote end deletes the session, screenshots, page source, URL, and window handles are no longer reliable. Keep capture bounded. A blocked diagnostic command can hold a Grid slot as effectively as a hung test.

The example uses the NUnit work directory and test ID rather than a display name. Display names can contain characters unsuitable for paths, and parallel parameterized cases can otherwise overwrite each other. Include a retry attempt in the path if your runner retries the same test ID.

Use OneTimeTearDown Only for Fixture-Owned Sessions

Some long journeys intentionally share a browser across tests in one fixture. If the suite accepts that coupling, permit fixtures to run in parallel with one another but do not permit children inside one fixture to race over its driver. Then [OneTimeSetUp] and [OneTimeTearDown] accurately describe ownership.

using NUnit.Framework;
using OpenQA.Selenium;

[TestFixture(BrowserKind.Chrome)]
[TestFixture(BrowserKind.Firefox)]
[Parallelizable(ParallelScope.Fixtures)]
public sealed class ReusedJourneyFixture
{
    private readonly BrowserKind _browser;
    private IWebDriver? _driver;

    public ReusedJourneyFixture(BrowserKind browser)
    {
        _browser = browser;
    }

    [OneTimeSetUp]
    public void StartFixtureBrowser()
    {
        _driver = DriverFactory.Create(_browser, gridUri: null);
    }

    [Test]
    [Order(1)]
    public void BeginJourney()
    {
        _driver!.Navigate().GoToUrl("https://www.selenium.dev/");
        Assert.That(_driver.Title, Does.Contain("Selenium"));
    }

    [OneTimeTearDown]
    public void StopFixtureBrowser()
    {
        IWebDriver? owned = Interlocked.Exchange(ref _driver, null);
        if (owned is null) return;
        try
        {
            owned.Quit();
        }
        finally
        {
            owned.Dispose();
        }
    }
}

Order documents sequence but also reveals dependency, which is a tradeoff rather than a best practice for independent tests. If the fixture has multiple dependent steps, report it as one journey or accept that an early browser failure invalidates later cases. Never combine a fixture-owned field with ParallelScope.All.

Isolate More Than IWebDriver

The Selenium guidance to avoid shared state includes application accounts, files, report buffers, and page objects. An instance-per-test fixture still collides if every case logs in as the same mutable user or writes failure.png into one directory.

Inject IWebDriver into page objects through constructors and keep those objects on the same fixture instance. Avoid static page objects, static waits, and static artifact collectors with mutable current-test fields. Use concurrent collections only for append-only reporting data keyed by immutable test ID; synchronization does not make a shared browser session semantically safe.

Remote sessions need capacity control. NUnit worker count can exceed matching Grid slots, especially in a mixed browser fixture matrix. Bound runner parallelism to the environment and observe session queueing rather than putting a semaphore inside the driver factory.

Analyze Parallel Failures by Ownership

If one test closes another test's browser, inspect fixture lifecycle attributes and static fields. A private field is not enough if one fixture instance serves parallel children. If tests pass with ParallelScope.Fixtures but fail with ParallelScope.All, that strongly suggests shared fixture state or shared application data.

If teardown reports an invalid session, determine whether the node disappeared, test code called Quit, or cleanup ran twice. The exchange-to-null pattern identifies double ownership in-process; Grid and driver logs distinguish remote loss. If screenshots are absent only on failures, confirm they are captured before release and that path creation is unique and writable.

If sessions leak after setup failures, assign _driver immediately after creation and keep subsequent setup inside the callback lifecycle. Avoid local variables that are never transferred to the field before another setup operation can throw.

Choose Isolation Over Accidental Speed

Per-test drivers add startup cost, but failures stay local and tests can run independently. Fixture reuse saves startups while coupling state, forcing serialization inside the fixture, and making a browser crash affect every remaining case. Measure the cost on your own environment before accepting that risk.

Instance-per-test-case creates more fixture objects, which are cheap compared with browsers and clearer than thread-indexed stores. Fixture-level reuse is reasonable for explicitly modeled journeys, not as a hidden optimization in a general base class.

Verify the Lifecycle Before Enabling Scale

• Parallel scope and fixture lifecycle attributes make field ownership unambiguous.
• The default path creates in [SetUp] and releases in [TearDown].
• Concurrent test cases never access the same fixture driver field.
• Artifact capture runs before quit and cannot prevent cleanup.
• Interlocked.Exchange transfers cleanup ownership once.
• Quit and Dispose are guarded without hiding the primary assertion.
• Artifact paths are unique for test ID, parameters, worker activity, and retries.
• Accounts, files, downloads, and page objects follow the test boundary.
• Fixture reuse is labeled, serialized within the fixture, and cleaned in [OneTimeTearDown].
• NUnit concurrency does not exceed matching local or Grid capacity.

Make the Attributes Tell the Truth

A sound NUnit Selenium framework does not depend on which worker happened to execute a method. Its attributes, fields, and callbacks state the ownership directly. Keep fresh sessions per test as the default, use fixture-scoped sessions only for deliberate serialized journeys, and make every release path idempotent. Then parallel fixtures increase throughput without weakening lifecycle correctness.