AppHarness Frontend Tests Hang on macOS When Using Bun

[martinzuern]

Describe the bug
A clear and concise description of what the bug is.

To Reproduce

1. Create a simple Reflex app with a test using AppHarness:

from pathlib import Path
from reflex.testing import AppHarness

def test_app_loads():
    app_root = Path(__file__).parent.parent
    harness = AppHarness.create(root=app_root, app_name="myapp.myapp")
    with harness:
        assert harness.frontend_url is not None

2. Run the test on macOS:

pytest tests/frontend/test_example.py -v -s

3. Observe that the test hangs after "Compiling: 100%" with no further progress.

Expected behavior

The frontend should compile and the test should proceed to execute browser interactions.

Specifics (please complete the following information):

• OS: macOS (tested on Apple Silicon)
• Python: 3.13.2
• Reflex: 0.8.x (with reflex[bun])
• Test framework: pytest with pytest-playwright

Actual Behavior

In roughly 50% of the cases, the test hangs indefinitely. The AppHarness._wait_frontend() method polls for self.frontend_url but never receives the "Compiled" message from the frontend subprocess stdout.

Root Cause Analysis

The issue appears to be related to how bun handles stdout buffering on macOS. When bun runs as a subprocess, its output is not being flushed to the parent process in a timely manner, causing _stream_reader() in AppHarness to never see the compilation completion message.

The relevant code in reflex/testing.py:

def _stream_reader(self, stream, ...):
    # Reads from frontend subprocess stdout
    for line in iter(stream.readline, b""):
        # Looking for "Compiled" message

Workaround

Setting REFLEX_USE_NPM=true environment variable forces Reflex to use npm instead of bun, which does not have the stdout buffering issue:

import os
os.environ["REFLEX_USE_NPM"] = "true"

Or in conftest.py:

import sys
import os

if sys.platform == "darwin":
    os.environ["REFLEX_USE_NPM"] = "true"

Suggested Fix

Consider one of the following approaches:

1. Add PTY support for bun subprocess - Use pty module to create a pseudo-terminal that forces line buffering
2. Document the macOS limitation - Add a note in the testing documentation about using npm on macOS
3. Auto-detect and fallback - When running AppHarness on macOS, automatically use npm instead of bun
4. Fix bun's stdout handling - Investigate if there's a bun configuration option to force stdout flushing

Additional Context

This issue only affects macOS. Linux CI environments using bun work correctly, possibly due to different subprocess I/O handling.