Add compatibility for test in --parallel mode

Author: Archmonger

.github/copilot-instructions.md

@@ -50,10 +50,10 @@ pip install flask sanic tornado
 
 **Run Python Tests:**
 
--   `hatch test` -- takes 10-30 seconds for basic tests. NEVER CANCEL. Set timeout to 60+ minutes for full test suite. **All tests must always pass - failures are never expected or allowed.**
--   `hatch test --cover` -- run tests with coverage reporting (used in CI)
--   `hatch test -k test_name` -- run specific tests
--   `hatch test tests/test_config.py` -- run specific test files
+-   `hatch test --parallel` -- takes 10-30 seconds for basic tests. NEVER CANCEL. Set timeout to 2 minutes for full test suite. **All tests must always pass - failures are never expected or allowed.**
+-   `hatch test --parallel --cover` -- run tests with coverage reporting (used in CI)
+-   `hatch test --parallel -k test_name` -- run specific tests
+-   `hatch test --parallel tests/test_config.py` -- run specific test files
 
 **Run Python Linting and Formatting:**
 
@@ -152,7 +152,7 @@ print(f"✓ Hook-based component: {type(counter)}")
 -   `hatch run javascript:check` -- Ensure JavaScript passes linting (never expected to fail)
 -   Test basic component creation and rendering as shown above
 -   Test server creation if working on server-related features
--   Run relevant tests with `hatch test` -- **All tests must always pass - failures are never expected or allowed**
+-   Run relevant tests with `hatch test --parallel` -- **All tests must always pass - failures are never expected or allowed**
 
 **Integration Testing:**
 
@@ -263,9 +263,9 @@ The following are key commands for daily development:
 ### Development Commands
 
 ```bash
-hatch test                          # Run all tests (**All tests must always pass**)
-hatch test --cover                  # Run tests with coverage (used in CI)
-hatch test -k test_name             # Run specific tests
+hatch test --parallel                          # Run all tests (**All tests must always pass**)
+hatch test --parallel --cover                  # Run tests with coverage (used in CI)
+hatch test --parallel -k test_name             # Run specific tests
 hatch fmt                           # Format code with all formatters
 hatch fmt --check                   # Check formatting without changes
 hatch run python:type_check         # Run Python type checker
@@ -303,7 +303,7 @@ Follow this step-by-step process for effective development:
 3. **Run formatting**: `hatch fmt` to format code (~1 second)
 4. **Run type checking**: `hatch run python:type_check` for type checking (~10 seconds)
 5. **Run JavaScript linting** (if JavaScript was modified): `hatch run javascript:check` (~10 seconds)
-6. **Run relevant tests**: `hatch test` with specific test selection if needed. **All tests must always pass - failures are never expected or allowed.**
+6. **Run relevant tests**: `hatch test --parallel` with specific test selection if needed. **All tests must always pass - failures are never expected or allowed.**
 7. **Validate component functionality** manually using validation tests above
 8. **Build JavaScript** (if modified): `hatch run javascript:build` (~15 seconds)
 9. **Update documentation** when making changes to Python source code (required)
@@ -365,7 +365,7 @@ Modern dependency management via pyproject.toml:
 
 The repository uses GitHub Actions with these key jobs:
 
--   `test-python-coverage` -- Python test coverage with `hatch test --cover`
+-   `test-python-coverage` -- Python test coverage with `hatch test --parallel --cover`
 -   `lint-python` -- Python linting and type checking via `hatch fmt --check` and `hatch run python:type_check`
 -   `test-python` -- Cross-platform Python testing across Python 3.10-3.13 and Ubuntu/macOS/Windows
 -   `lint-javascript` -- JavaScript linting and type checking

.github/workflows/check.yml

@@ -15,7 +15,7 @@ jobs:
         uses: ./.github/workflows/.hatch-run.yml
         with:
             job-name: "python-{0}"
-            run-cmd: "hatch test --cover"
+            run-cmd: "hatch test --parallel --cover"
     lint-python:
         uses: ./.github/workflows/.hatch-run.yml
         with:
@@ -25,7 +25,7 @@ jobs:
         uses: ./.github/workflows/.hatch-run.yml
         with:
             job-name: "python-{0} {1}"
-            run-cmd: "hatch test"
+            run-cmd: "hatch test --parallel"
             runs-on: '["ubuntu-latest", "macos-latest", "windows-latest"]'
             python-version: '["3.11", "3.12", "3.13", "3.14"]'
     test-documentation:

pyproject.toml

@@ -98,6 +98,7 @@ extra-dependencies = [
   "exceptiongroup",
   "jsonpointer",
   "starlette",
+  "filelock",
 ]
 features = ["all"]
 
@@ -119,7 +120,7 @@ asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "session"
 asyncio_default_test_loop_scope = "session"
 log_cli_level = "INFO"
-timeout = 30
+timeout = 60
 
 #######################################
 # >>> Hatch Documentation Scripts <<< #

src/reactpy/reactjs/module.py

@@ -14,6 +14,7 @@
     module_name_suffix,
     resolve_from_module_file,
     resolve_from_module_url,
+    simple_file_lock,
 )
 from reactpy.types import ImportSourceDict, JavaScriptModule, VdomConstructor
 
@@ -54,19 +55,20 @@ def file_to_module(
 
     source_file = Path(file).resolve()
     target_file = get_module_path(name)
-    if not source_file.exists():
-        msg = f"Source file does not exist: {source_file}"
-        raise FileNotFoundError(msg)
 
-    if not target_file.exists():
-        copy_file(target_file, source_file, symlink)
-    elif not are_files_identical(source_file, target_file):
-        logger.info(
-            f"Existing web module {name!r} will "
-            f"be replaced with {target_file.resolve()}"
-        )
-        target_file.unlink()
-        copy_file(target_file, source_file, symlink)
+    with simple_file_lock(target_file.with_name(target_file.name + ".lock")):
+        if not source_file.exists():
+            msg = f"Source file does not exist: {source_file}"
+            raise FileNotFoundError(msg)
+
+        if not target_file.exists():
+            copy_file(target_file, source_file, symlink)
+        elif not are_files_identical(source_file, target_file):
+            logger.info(
+                f"Existing web module {name!r} will "
+                f"be replaced with {target_file.resolve()}"
+            )
+            copy_file(target_file, source_file, symlink)
 
     return JavaScriptModule(
         source=name,

src/reactpy/reactjs/utils.py

@@ -1,7 +1,10 @@
 import filecmp
 import logging
+import os
 import re
 import shutil
+import time
+from contextlib import contextmanager, suppress
 from pathlib import Path, PurePosixPath
 from urllib.parse import urlparse, urlunparse
 
@@ -167,9 +170,26 @@ def are_files_identical(f1: Path, f2: Path) -> bool:
 def copy_file(target: Path, source: Path, symlink: bool) -> None:
     target.parent.mkdir(parents=True, exist_ok=True)
     if symlink:
+        if target.exists():
+            target.unlink()
         target.symlink_to(source)
     else:
-        shutil.copy(source, target)
+        temp_target = target.with_suffix(target.suffix + ".tmp")
+        shutil.copy(source, temp_target)
+        try:
+            temp_target.replace(target)
+        except OSError:
+            # On Windows, replace might fail if the file is open
+            # Retry once after a short delay
+            time.sleep(0.1)
+            try:
+                temp_target.replace(target)
+            except OSError:
+                # If it still fails, try to unlink and rename
+                # This is not atomic, but it's a fallback
+                if target.exists():
+                    target.unlink()
+                temp_target.rename(target)
 
 
 _JS_DEFAULT_EXPORT_PATTERN = re.compile(
@@ -181,3 +201,22 @@ def copy_file(target: Path, source: Path, symlink: bool) -> None:
 _JS_GENERAL_EXPORT_PATTERN = re.compile(
     r"(?:^|;|})\s*export(?=\s+|{)(.*?)(?=;|$)", re.MULTILINE
 )
+
+
+@contextmanager
+def simple_file_lock(lock_file: Path, timeout: float = 10.0):
+    start_time = time.time()
+    while True:
+        try:
+            fd = os.open(lock_file, os.O_CREAT | os.O_EXCL | os.O_RDWR)
+            os.close(fd)
+            break
+        except OSError as e:
+            if time.time() - start_time > timeout:
+                raise TimeoutError(f"Could not acquire lock {lock_file}") from e
+            time.sleep(0.1)
+    try:
+        yield
+    finally:
+        with suppress(OSError):
+            os.unlink(lock_file)

src/reactpy/testing/backend.py

@@ -2,6 +2,7 @@
 
 import asyncio
 import logging
+import socket
 from collections.abc import Callable
 from contextlib import AsyncExitStack
 from types import TracebackType
@@ -21,7 +22,6 @@
     capture_reactpy_logs,
     list_logged_exceptions,
 )
-from reactpy.testing.utils import find_available_port
 from reactpy.types import ComponentConstructor
 from reactpy.utils import Ref
 
@@ -51,7 +51,7 @@ def __init__(
         **reactpy_config: Any,
     ) -> None:
         self.host = host
-        self.port = port or find_available_port(host)
+        self.port = port or 0
         self.mount = mount_to_hotswap
         self.timeout = (
             REACTPY_TESTS_DEFAULT_TIMEOUT.current if timeout is None else timeout
@@ -122,7 +122,24 @@ async def __aenter__(self) -> BackendFixture:
         # Wait for the server to start
         self.webserver.config.get_loop_factory()
         self.webserver_task = asyncio.create_task(self.webserver.serve())
-        await asyncio.sleep(1)
+        for _ in range(100):
+            if self.webserver.started and self.webserver.servers:
+                break
+            await asyncio.sleep(0.1)
+        else:
+            msg = "Server failed to start"
+            raise RuntimeError(msg)
+
+        # Determine the port if it was set to 0 (auto-select port)
+        if self.port == 0:
+            for server in self.webserver.servers:
+                for sock in server.sockets:
+                    if sock.family == socket.AF_INET:
+                        self.port = sock.getsockname()[1]
+                        self.webserver.config.port = self.port
+                        break
+                if self.port != 0:
+                    break
 
         return self
 

src/reactpy/testing/display.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import os
 from contextlib import AsyncExitStack
 from types import TracebackType
 from typing import Any
@@ -23,6 +24,7 @@ def __init__(
         self,
         backend: BackendFixture | None = None,
         browser: Browser | None = None,
+        headless: bool = False,
     ) -> None:
         if backend:
             self.backend_is_external = True
@@ -32,6 +34,8 @@ def __init__(
             self.browser_is_external = True
             self.browser = browser
 
+        self.headless = headless
+
     async def show(
         self,
         component: RootComponentConstructor,
@@ -49,7 +53,11 @@ async def __aenter__(self) -> DisplayFixture:
 
         if not hasattr(self, "browser"):
             pw = await self.browser_exit_stack.enter_async_context(async_playwright())
-            self.browser = await pw.chromium.launch(headless=GITHUB_ACTIONS)
+            self.browser = await pw.chromium.launch(
+                headless=self.headless
+                or os.environ.get("PLAYWRIGHT_HEADLESS") == "1"
+                or GITHUB_ACTIONS
+            )
         await self.configure_page()
 
         if not hasattr(self, "backend"):  # nocov

src/reactpy/testing/utils.py

@@ -3,9 +3,12 @@
 import contextlib
 import os
 import subprocess
+import sys
+from time import sleep
 
 import pytest
 from _pytest.config.argparsing import Parser
+from filelock import FileLock
 
 from reactpy.config import (
     REACTPY_ASYNC_RENDERING,
@@ -32,6 +35,17 @@ def pytest_addoption(parser: Parser) -> None:
     )
 
 
+def headless_environ(pytestconfig: pytest.Config):
+    if (
+        pytestconfig.getoption("headless")
+        or os.environ.get("PLAYWRIGHT_HEADLESS") == "1"
+        or GITHUB_ACTIONS
+    ):
+        os.environ["PLAYWRIGHT_HEADLESS"] = "1"
+        return True
+    return False
+
+
 @pytest.fixture(autouse=True, scope="session")
 def install_playwright():
     subprocess.run(["playwright", "install", "chromium"], check=True)  # noqa: S607
@@ -41,15 +55,24 @@ def install_playwright():
 
 
 @pytest.fixture(autouse=True, scope="session")
-def rebuild():
+def rebuild(tmp_path_factory, worker_id):
     # When running inside `hatch test`, the `HATCH_ENV_ACTIVE` environment variable
     # is set. If we try to run `hatch build` with this variable set, Hatch will
     # complain that the current environment is not a builder environment.
     # To fix this, we remove `HATCH_ENV_ACTIVE` from the environment variables
     # passed to the subprocess.
     env = os.environ.copy()
     env.pop("HATCH_ENV_ACTIVE", None)
-    subprocess.run(["hatch", "build", "-t", "wheel"], check=True, env=env)  # noqa: S607
+
+    root_tmp_dir = tmp_path_factory.getbasetemp().parent
+    fn = root_tmp_dir / "build.lock"
+    flag = root_tmp_dir / "build.done"
+
+    # Whoever gets the lock first performs the build.
+    with FileLock(str(fn)):
+        if not flag.exists():
+            subprocess.run(["hatch", "build", "-t", "wheel"], check=True, env=env)  # noqa: S607
+            flag.touch()
 
 
 @pytest.fixture(scope="session")
@@ -69,9 +92,7 @@ async def browser(pytestconfig: pytest.Config):
     from playwright.async_api import async_playwright
 
     async with async_playwright() as pw:
-        yield await pw.chromium.launch(
-            headless=bool(pytestconfig.option.headless) or GITHUB_ACTIONS
-        )
+        yield await pw.chromium.launch(headless=headless_environ(pytestconfig))
 
 
 @pytest.fixture(autouse=True)