fix: prevent ProtocolCallback memory leak during tracing (#2977)

Fix memory leak where ProtocolCallback objects accumulated when tracing
was enabled. The issue affected both sync and async Playwright, but was
more severe in async usage where callbacks persisted permanently.

- When tracing is enabled, send_no_reply() creates ProtocolCallback objects
- These callbacks have circular references via task cancellation handlers
- For no_reply messages, futures are never resolved, preventing GC cleanup
- Each page operation during tracing leaked ~10 callbacks permanently

- Add no_reply parameter to ProtocolCallback constructor
- For no_reply=True: skip cancellation setup and resolve future immediately
- For no_reply=False: use full constructor with cancellation handling
- Update dispatch() to handle missing callbacks gracefully

- Added regression test in test_reference_count_async.py
- Test fails before fix (30+ leaked callbacks) and passes after (≤5)
- All existing tracing and asyncio tests continue to pass

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: mxschmitt

playwright/_impl/_connection.py

@@ -218,10 +218,16 @@ def remove_listener(self, event: str, f: Any) -> None:
 
 
 class ProtocolCallback:
-    def __init__(self, loop: asyncio.AbstractEventLoop) -> None:
+    def __init__(self, loop: asyncio.AbstractEventLoop, no_reply: bool = False) -> None:
         self.stack_trace: traceback.StackSummary
-        self.no_reply: bool
+        self.no_reply = no_reply
         self.future = loop.create_future()
+
+        # Skip cancellation setup for no_reply callbacks to avoid circular references
+        if no_reply:
+            self.future.set_result(None)
+            return
+
         # The outer task can get cancelled by the user, this forwards the cancellation to the inner task.
         current_task = asyncio.current_task()
 
@@ -360,14 +366,7 @@ def _send_message_to_server(
             )
         self._last_id += 1
         id = self._last_id
-        callback = ProtocolCallback(self._loop)
-        task = asyncio.current_task(self._loop)
-        callback.stack_trace = cast(
-            traceback.StackSummary,
-            getattr(task, "__pw_stack_trace__", traceback.extract_stack(limit=10)),
-        )
-        callback.no_reply = no_reply
-        self._callbacks[id] = callback
+
         stack_trace_information = cast(ParsedStackTrace, self._api_zone.get())
         frames = stack_trace_information.get("frames", [])
         location = (
@@ -400,6 +399,18 @@ def _send_message_to_server(
             self.local_utils.add_stack_to_tracing_no_reply(id, frames)
 
         self._transport.send(message)
+
+        # For no_reply messages, create lightweight callback without cancellation setup
+        if no_reply:
+            return ProtocolCallback(self._loop, no_reply=True)
+
+        # For messages that expect replies, create full callback with cancellation handling
+        callback = ProtocolCallback(self._loop, no_reply=False)
+        task = asyncio.current_task(self._loop)
+        callback.stack_trace = cast(
+            traceback.StackSummary,
+            getattr(task, "__pw_stack_trace__", traceback.extract_stack(limit=10)),
+        )
         self._callbacks[id] = callback
 
         return callback
@@ -409,7 +420,10 @@ def dispatch(self, msg: ParsedMessagePayload) -> None:
             return
         id = msg.get("id")
         if id:
-            callback = self._callbacks.pop(id)
+            callback = self._callbacks.pop(id, None)
+            # If callback doesn't exist, it was likely a no_reply message
+            if callback is None:
+                return
             if callback.future.cancelled():
                 return
             # No reply messages are used to e.g. waitForEventInfo(after) which returns exceptions on page close.

tests/test_reference_count_async.py

@@ -13,6 +13,8 @@
 # limitations under the License.
 
 import gc
+import os
+import tempfile
 from collections import defaultdict
 from typing import Any
 
@@ -71,3 +73,62 @@ def handle_network_response_received(event: Any) -> None:
     assert "Dialog" not in pw_objects
     assert "Request" not in pw_objects
     assert "Route" not in pw_objects
+
+
+@pytest.mark.asyncio
+async def test_tracing_should_not_leak_protocol_callbacks(browser_name: str) -> None:
+    """
+    Regression test for https://github.com/microsoft/playwright-python/issues/2977
+
+    This test ensures that ProtocolCallback objects don't accumulate when tracing is enabled.
+    The memory leak occurred because no_reply callbacks were created with circular references
+    but never cleaned up.
+    """
+
+    def count_protocol_callbacks() -> int:
+        """Count ProtocolCallback objects in memory."""
+        gc.collect()
+        count = 0
+        for obj in gc.get_objects():
+            if (
+                hasattr(obj, "__class__")
+                and obj.__class__.__name__ == "ProtocolCallback"
+            ):
+                count += 1
+        return count
+
+    with tempfile.TemporaryDirectory() as temp_dir:
+        trace_file = os.path.join(temp_dir, "test_trace.zip")
+
+        async with async_playwright() as p:
+            browser = await p[browser_name].launch()
+            context = await browser.new_context()
+
+            # Start tracing to trigger the creation of no_reply callbacks
+            await context.tracing.start(screenshots=True, snapshots=True)
+
+            initial_count = count_protocol_callbacks()
+
+            # Perform operations that would create tracing callbacks
+            for _ in range(3):
+                page = await context.new_page()
+                await page.goto("data:text/html,<h1>Test Page</h1>")
+                await page.wait_for_load_state("networkidle")
+                await page.evaluate(
+                    "document.querySelector('h1').textContent = 'Modified'"
+                )
+                await page.close()
+
+            # Stop tracing
+            await context.tracing.stop(path=trace_file)
+            await browser.close()
+
+    # Force garbage collection and check callback count
+    gc.collect()
+    final_count = count_protocol_callbacks()
+
+    # The key assertion: callback count should not have increased significantly
+    # Allow for a small number of legitimate callbacks but ensure no major leak
+    assert (
+        final_count - initial_count <= 5
+    ), f"ProtocolCallback leak detected: initial={initial_count}, final={final_count}, leaked={final_count - initial_count}"