← ./articles

Tauri WebDriver Cannot Start? Clear Stale Driver Processes

tauriwebdriverwindowse2e-testingdebugging

A Tauri E2E run times out before navigation, reports an address already in use, or cannot create a WebDriver session. The application code may be fine: a driver from the previous run can still own the port.

Treat driver startup as an environment boundary. Identify the listener, clean up only the process you own, and prove that the new session uses the expected driver and application binary.

Identify a lifecycle failure before editing app code

Driver-level symptoms include:

  • the test fails before the first DOM assertion
  • a local WebDriver port is already listening before the test starts
  • retrying changes the error without changing application code
  • the app launches but the harness cannot create or attach to a session

Save the verbatim error and startup timestamps. If the same UI test reaches the DOM and then fails an assertion, this article is probably not the right diagnosis.

Find the process that owns the port

Use the configured port from your harness; do not assume every setup uses the same one.

$port = 4444
$connection = Get-NetTCPConnection -LocalPort $port -State Listen -ErrorAction SilentlyContinue
$connection | Select-Object LocalAddress, LocalPort, OwningProcess

Then inspect the owner:

Get-Process -Id $connection.OwningProcess |
  Select-Object Id, ProcessName, Path, StartTime

Do not terminate a PID until its path and process name show that it belongs to the test run. A port number alone is not ownership evidence.

Stop the stale driver and wait for release

After confirming the process, stop that PID through the harness teardown when possible. For manual recovery:

Stop-Process -Id $connection.OwningProcess

do {
  Start-Sleep -Milliseconds 200
  $listener = Get-NetTCPConnection -LocalPort $port -State Listen -ErrorAction SilentlyContinue
} while ($listener)

The short poll matters. Starting a new driver immediately can race with operating-system cleanup.

Always put normal teardown in afterEach, afterAll, or finally. A failed assertion should not skip driver shutdown.

Give one component ownership of the native driver

Modern WebdriverIO Tauri setups can use an embedded provider, which avoids a separately managed native driver. If you drive tauri-driver directly on Windows, it uses Microsoft Edge WebDriver underneath.

Do not pre-start msedgedriver when the harness expects to start it. If you manage the native executable yourself, pass the documented path and make that layer responsible for both startup and shutdown. Two owners create duplicate processes and ambiguous logs.

Verify driver compatibility and binary freshness

For a direct native-driver setup, confirm that Microsoft Edge and Edge Driver are compatible. Tauri's current WebdriverIO service can manage that synchronization on the external-driver route, but custom harnesses must still make the versions and executable path explicit.

Also verify the application artifact:

  • rebuild after source changes
  • log the exact binary path launched by the test
  • compare its modification time with the build completion time
  • if the binary loads a configured dev URL, confirm that URL serves the current frontend

A clean WebDriver session attached to an old binary is still a failed test setup.

Prove startup and teardown

Record four checkpoints:

Before start: no unexpected listener
After driver start: expected PID owns the port
After session creation: session ID and DOM ready observed
After teardown: process exited and port released

This evidence distinguishes an application failure from a leaked driver, incompatible native driver, or stale artifact.

References

Summary

When Tauri WebDriver cannot start, inspect the port owner before changing app code. Stop only a verified stale driver, wait for port release, give one layer lifecycle ownership, and verify both driver compatibility and the launched application artifact.