From 8f71481a1b76350c7b96fcd01f0ac26418be7a71 Mon Sep 17 00:00:00 2001 From: DJ Lee Date: Fri, 13 Nov 2026 18:08:10 -0500 Subject: [PATCH 1/2] Make tab navigation more robust against race conditions --- src/py/kaleido/_kaleido_tab/_tab.py | 84 +++++++--- src/py/tests/test_kaleido_tab.py | 240 +++++++++++++++++++++++++--- 2 files changed, 283 insertions(+), 41 deletions(-) diff --git a/src/py/kaleido/_kaleido_tab/_tab.py b/src/py/kaleido/_kaleido_tab/_tab.py index 93094809..d8ab0e49 100644 --- a/src/py/kaleido/_kaleido_tab/_tab.py +++ b/src/py/kaleido/_kaleido_tab/_tab.py @@ -1,5 +1,6 @@ from __future__ import annotations +import asyncio import base64 from typing import TYPE_CHECKING @@ -10,7 +11,6 @@ from ._errors import _raise_error if TYPE_CHECKING: - import asyncio from pathlib import Path import choreographer as choreo @@ -68,32 +68,72 @@ async def navigate(self, url: str | Path = ""): url: Override the location of the kaleidofier script if necessary. """ - # Subscribe to event which will contain javascript engine ID (need it - # for calling javascript functions) - javascript_ready = _subscribe_new(self.tab, "Runtime.executionContextCreated") - - # Subscribe to event indicating page ready. - page_ready = _subscribe_new(self.tab, "Page.loadEventFired") + # Subscribe to event indicating that page or a subframe has loaded. We queue + # these events and filter them afterwards once we know the IDs from our + # navigation. We can't simply wait for the first load event, because it could + # come from Chrome's new tab page. + load_events: asyncio.Queue[dict] = asyncio.Queue() - # Apply headers if they exist - await self._apply_headers() + async def on_lifecycle(event): + if event["params"]["name"] == "load": + load_events.put_nowait(event["params"]) - # Enable Page events before navigation; completed load events are not replayed. - _logger.debug2(f"Calling Page.enable on {self.tab}") - _raise_error(await self.tab.send_command("Page.enable")) + self.tab.subscribe("Page.lifecycleEvent", on_lifecycle) - # Navigating page. This will trigger the above events. - _logger.debug2(f"Calling Page.navigate on {self.tab}") - _raise_error(await self.tab.send_command("Page.navigate", params={"url": url})) + try: + await self._apply_headers() - # Enabling javascript events (for javascript_ready). - # We do this after navigation to receive the new execution context. - _logger.debug2(f"Calling Runtime.enable on {self.tab}") - _raise_error(await self.tab.send_command("Runtime.enable")) - - self._current_js_id = _dtools.get_js_id(await javascript_ready) + # Enable events before navigating so fast loads cannot be missed. + _logger.debug2(f"Calling Page.enable on {self.tab}") + _raise_error(await self.tab.send_command("Page.enable")) + _raise_error( + await self.tab.send_command( + "Page.setLifecycleEventsEnabled", + params={"enabled": True}, + ), + ) - await page_ready # don't care result, ready is ready + # Navigating page. This will trigger the above events. + _logger.debug2(f"Calling Page.navigate on {self.tab}") + _raise_error( + navigate_response := await self.tab.send_command( + "Page.navigate", params={"url": url} + ) + ) + navigation = navigate_response["result"] + if error := navigation.get("errorText"): + raise RuntimeError(f"Navigation to {url} failed: {error}") + + # Wait for the correct load event which matches the navigation we made. + while True: + loaded = await load_events.get() + if ( + loaded["frameId"] == navigation["frameId"] + and loaded["loaderId"] == navigation["loaderId"] + ): + break + finally: + self.tab.unsubscribe("Page.lifecycleEvent") + + # Runtime.enable reports existing contexts; wait for load to avoid old ones. + contexts: asyncio.Queue[int] = asyncio.Queue() + + async def on_context_created(event): + context = event["params"]["context"] + aux = context.get("auxData", {}) + if ( + aux.get("frameId") == navigation["frameId"] + and aux.get("isDefault") is True + ): + contexts.put_nowait(context["id"]) + + self.tab.subscribe("Runtime.executionContextCreated", on_context_created) + try: + _logger.debug2(f"Calling Runtime.enable on {self.tab}") + _raise_error(await self.tab.send_command("Runtime.enable")) + self._current_js_id = await contexts.get() + finally: + self.tab.unsubscribe("Runtime.executionContextCreated") # this runs *after* page load because running it first thing # requires a couple extra lines diff --git a/src/py/tests/test_kaleido_tab.py b/src/py/tests/test_kaleido_tab.py index e1ff642d..2727a4f2 100644 --- a/src/py/tests/test_kaleido_tab.py +++ b/src/py/tests/test_kaleido_tab.py @@ -2,38 +2,240 @@ from unittest.mock import AsyncMock, Mock import choreographer +import pytest +from choreographer.errors import DevtoolsProtocolError from kaleido._kaleido_tab import _KaleidoTab -async def test_navigate_when_page_loads_before_navigation_returns(): +@pytest.fixture +def tab_events(): tab = Mock(spec=choreographer.Tab) - javascript_ready = asyncio.get_running_loop().create_future() - page_ready = asyncio.get_running_loop().create_future() - tab.subscribe_once.side_effect = { - "Runtime.executionContextCreated": javascript_ready, - "Page.loadEventFired": page_ready, - }.__getitem__ - page_enabled = False + callbacks = {} + + async def emit(event, **params): + message = {"method": event, "params": params} + if event in callbacks: + await callbacks[event](message) + + tab.subscribe.side_effect = callbacks.__setitem__ + tab.unsubscribe.side_effect = lambda event: callbacks.pop(event, None) + return tab, emit + + +@pytest.mark.parametrize("load_before_response", [True, False]) +@pytest.mark.parametrize( + ("frame_id", "loader_id", "event_name"), + [ + ("main", "old-document", "load"), + ("child", "new-document", "load"), + ("main", "new-document", "DOMContentLoaded"), + ], +) +async def test_navigate_waits_for_its_document( + tab_events, + load_before_response, + frame_id, + loader_id, + event_name, +): + tab, emit = tab_events + enabled = set() + event_commands = {"Page.enable", "Page.setLifecycleEventsEnabled"} navigated_context_id = 2 - context_id = 1 + navigated = asyncio.Event() + + async def loaded(): + # A fast load must be observed even before Page.navigate returns. + if event_commands <= enabled: + await emit("Page.loadEventFired", timestamp=2) + await emit( + "Page.lifecycleEvent", + frameId="main", + loaderId="new-document", + name="load", + ) async def send_command(command, params=None): # noqa: ARG001 - nonlocal page_enabled, context_id - if command == "Page.enable": - page_enabled = True + if command in event_commands: + enabled.add(command) elif command == "Page.navigate": - context_id = navigated_context_id - # Chrome does not replay a load event missed while Page was disabled. - if page_enabled: - page_ready.set_result({}) + await emit("Page.loadEventFired", timestamp=1) + if "Page.setLifecycleEventsEnabled" in enabled: + await emit( + "Page.lifecycleEvent", + frameId=frame_id, + loaderId=loader_id, + name=event_name, + ) + if load_before_response: + await loaded() + navigated.set() + return {"result": {"frameId": "main", "loaderId": "new-document"}} elif command == "Runtime.enable": - javascript_ready.set_result({"params": {"context": {"id": context_id}}}) + await emit( + "Runtime.executionContextCreated", + context={ + "id": navigated_context_id, + "auxData": {"frameId": "main", "isDefault": True}, + }, + ) + return {"result": {}} + + tab.send_command = AsyncMock(side_effect=send_command) + kaleido_tab = _KaleidoTab(tab) + navigation = asyncio.create_task(kaleido_tab.navigate("file:///index.html")) + try: + await asyncio.wait_for(navigated.wait(), timeout=1) + if not load_before_response: + assert not navigation.done() + assert not any( + call.args[0] == "Runtime.enable" + for call in tab.send_command.await_args_list + ) + await loaded() + await asyncio.wait_for(navigation, timeout=1) + assert kaleido_tab._current_js_id == navigated_context_id # noqa: SLF001 + tab.unsubscribe.assert_any_call("Page.lifecycleEvent") + finally: + navigation.cancel() + await asyncio.gather(navigation, return_exceptions=True) + + +@pytest.mark.parametrize("context_before_response", [True, False]) +async def test_navigate_selects_main_frame_default_context( + tab_events, context_before_response +): + tab, emit = tab_events + runtime_enabled = asyncio.Event() + navigated_context_id = 4 + + async def context_ready(): + await emit( + "Runtime.executionContextCreated", + context={ + "id": navigated_context_id, + "auxData": {"frameId": "main", "isDefault": True}, + }, + ) + + async def send_command(command, params=None): # noqa: ARG001 + if command == "Page.navigate": + await emit( + "Page.lifecycleEvent", + frameId="main", + loaderId="new-document", + name="load", + ) + return {"result": {"frameId": "main", "loaderId": "new-document"}} + if command == "Runtime.enable": + for context in ( + {"id": 1, "auxData": {"frameId": "child", "isDefault": True}}, + {"id": 2, "auxData": {"frameId": "main", "isDefault": False}}, + {"id": 3}, + ): + await emit("Runtime.executionContextCreated", context=context) + if context_before_response: + await context_ready() + runtime_enabled.set() return {"result": {}} tab.send_command = AsyncMock(side_effect=send_command) kaleido_tab = _KaleidoTab(tab) + navigation = asyncio.create_task(kaleido_tab.navigate("file:///index.html")) + try: + await asyncio.wait_for(runtime_enabled.wait(), timeout=1) + if not context_before_response: + assert not navigation.done() + await context_ready() + await asyncio.wait_for(navigation, timeout=1) + assert kaleido_tab._current_js_id == navigated_context_id # noqa: SLF001 + tab.unsubscribe.assert_any_call("Runtime.executionContextCreated") + finally: + navigation.cancel() + await asyncio.gather(navigation, return_exceptions=True) + - await asyncio.wait_for(kaleido_tab.navigate("file:///index.html"), timeout=1) +@pytest.mark.parametrize( + ("failed_command", "response", "error", "message"), + [ + ( + "Page.navigate", + {"result": {"errorText": "net::ERR_FILE_NOT_FOUND"}}, + RuntimeError, + "net::ERR_FILE_NOT_FOUND", + ), + ( + "Page.navigate", + {"error": {"code": -32000, "message": "Navigation failed"}}, + DevtoolsProtocolError, + "Navigation failed", + ), + ( + "Runtime.enable", + {"error": {"code": -32000, "message": "Runtime unavailable"}}, + DevtoolsProtocolError, + "Runtime unavailable", + ), + ], +) +async def test_navigate_cleans_up_after_failure( + tab_events, failed_command, response, error, message +): + tab, emit = tab_events + + async def send_command(command, params=None): # noqa: ARG001 + if command == failed_command: + return response + if command == "Page.navigate": + await emit( + "Page.lifecycleEvent", + frameId="main", + loaderId="new-document", + name="load", + ) + return {"result": {"frameId": "main", "loaderId": "new-document"}} + return {"result": {}} + + tab.send_command = AsyncMock(side_effect=send_command) + with pytest.raises(error, match=message): + await asyncio.wait_for( + _KaleidoTab(tab).navigate("file:///missing.html"), timeout=1 + ) + tab.unsubscribe.assert_any_call("Page.lifecycleEvent") + if failed_command == "Runtime.enable": + tab.unsubscribe.assert_any_call("Runtime.executionContextCreated") - assert kaleido_tab._current_js_id == navigated_context_id # noqa: SLF001 + +@pytest.mark.parametrize("waiting_for_context", [True, False]) +async def test_navigate_cleans_up_after_cancellation(tab_events, waiting_for_context): + tab, emit = tab_events + ready_to_cancel = asyncio.Event() + + async def send_command(command, params=None): # noqa: ARG001 + if command == "Page.navigate": + if waiting_for_context: + await emit( + "Page.lifecycleEvent", + frameId="main", + loaderId="new-document", + name="load", + ) + else: + ready_to_cancel.set() + return {"result": {"frameId": "main", "loaderId": "new-document"}} + if command == "Runtime.enable": + ready_to_cancel.set() + return {"result": {}} + + tab.send_command = AsyncMock(side_effect=send_command) + navigation = asyncio.create_task(_KaleidoTab(tab).navigate("file:///index.html")) + try: + await asyncio.wait_for(ready_to_cancel.wait(), timeout=1) + finally: + navigation.cancel() + await asyncio.gather(navigation, return_exceptions=True) + assert navigation.cancelled() + tab.unsubscribe.assert_any_call("Page.lifecycleEvent") + if waiting_for_context: + tab.unsubscribe.assert_any_call("Runtime.executionContextCreated") From 7150edbbff7ce14272502f3e937b0d15cb6845b1 Mon Sep 17 00:00:00 2001 From: Cameron DeCoster Date: Wed, 18 Nov 2026 11:19:30 -0700 Subject: [PATCH 2/2] Update changelog --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index d575661a..fdbf083e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,8 @@ ## Unreleased +### Fixed +- Fix intermittent `ReferenceError: kaleido_scopes is not defined` during exports by waiting for the load event of the Kaleido page itself [[#488](https://github.com/plotly/kaleido/pull/488)], with thanks to @dennisjlee for the contribution! + ## v1.5.1 -- 2026-11-12 ### Fixed