Skip to content

Commit 126c410

Browse files
petercorkeclaude
andauthored
fix(lite): the notebooks install the wheel built with the site, and a browser check proves it (#863)
The bootstrap looked for the bundled wheel in /pypi, which does not exist in the kernel, so JupyterLite always installed the last release from PyPI. Install through piplite, which looks in the site's own index first. The Node check stands in for piplite and also plots a trajectory under ipympl; a new Playwright check builds a site with the wheel and checks the install, ipywidgets, an ipympl figure and an animation in Chromium. Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
1 parent 6497cdc commit 126c410

19 files changed

Lines changed: 537 additions & 165 deletions

‎.github/workflows/docs.yml‎

Lines changed: 23 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -91,18 +91,13 @@ jobs:
9191
# Copies *.ipynb plus any local asset directories (e.g.
9292
# docs/notebooks/figs/, referenced by relative path from markdown
9393
# cells) -- but not the Makefile-generated *.py script conversions
94-
# or other loose files. ik_benchmark.ipynb is excluded deliberately:
95-
# it benchmarks numeric IK solver performance and uses the
96-
# websocket-based Swift visualizer, neither of which is meaningful
97-
# or functional inside the Pyodide sandbox -- it stays Colab-only.
98-
# ik-symbolic.ipynb is included: SymPy is one of Pyodide's own packages
94+
# or other loose files. ik-symbolic.ipynb is included: SymPy is one of Pyodide's own packages
9995
# and the derivation takes 1 to 10 s without python-flint (timed in
10096
# docs/lite/wasm_check, which checks it on every build).
10197
run: |
10298
mkdir -p docs/lite/files
10399
rsync -a --exclude '.ipynb_checkpoints' --exclude '__pycache__' \
104100
--exclude 'Untitled*.ipynb' --exclude '*.py' --exclude 'Makefile' --exclude 'README.md' \
105-
--exclude 'ik_benchmark.ipynb' \
106101
docs/notebooks/ docs/lite/files/
107102
108103
- name: Adapt staged notebooks for JupyterLite
@@ -156,6 +151,28 @@ jobs:
156151
pip install jupyterlite-core "jupyterlite-pyodide-kernel==0.6.1" jupyter-server ipympl
157152
cd docs/lite && jupyter lite build --output-dir ../build/html/lite
158153
154+
- name: Check JupyterLite in a real browser (install, widgets, animation)
155+
# Builds a small site with the wheel built above and one notebook, opens it in
156+
# Chromium, and checks that the site installs that wheel (not the last release
157+
# from PyPI), draws an ipywidgets slider and an ipympl figure, and that a
158+
# trajectory animates while its cell is running. See
159+
# docs/lite/browser_check/. Informational (continue-on-error) until it has
160+
# run green on main, then remove that line so that it blocks the deploy.
161+
continue-on-error: true
162+
timeout-minutes: 20
163+
run: |
164+
pip install playwright
165+
playwright install --with-deps chromium
166+
python docs/lite/browser_check/check_lite_in_browser.py --screenshot lite_check_failed.png
167+
168+
- name: Keep the screenshot if the browser check failed
169+
if: ${{ !cancelled() }}
170+
uses: actions/upload-artifact@v7
171+
with:
172+
name: lite-browser-check
173+
path: lite_check_failed.png
174+
if-no-files-found: ignore
175+
159176
- name: Upload Pages artifact
160177
uses: actions/upload-pages-artifact@v5
161178
with:

‎docs/lite/browser_check/README.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# JupyterLite browser check
2+
3+
Runs JupyterLite in a real browser (Chromium, with Playwright) and checks what the
4+
Node check in `../wasm_check/` cannot see: that the site installs the toolbox that was
5+
built with it, and that plots and widgets work.
6+
7+
`check_lite_in_browser.py` builds a small site from `docs/lite` (its configuration and
8+
the wheel in `docs/lite/pypi`) plus one notebook that it writes, `browser_check.ipynb`,
9+
which starts with the real generated bootstrap cell. It opens that in Chromium and runs
10+
the notebook, which requires:
11+
12+
| Check | Why |
13+
|---|---|
14+
| the bootstrap cell prints `Running in browser using RTB v...` | the install path works at all |
15+
| a hash of the installed `PyPlot.py` equals that of the checkout | the site installs the wheel built with it, not the last release from PyPI (a plain `micropip.install` cannot see the site's own index, `piplite` can; this is what went wrong once and nothing else noticed) |
16+
| an `ipywidgets` slider is drawn | widgets work in JupyterLite |
17+
| an `ipympl` figure of one pose is drawn | `%matplotlib ipympl`, which the notebooks use, works |
18+
| a trajectory shows at least 5 different images while its cell is running | an `ipympl` figure cannot update while a cell runs, so the Toolbox pushes inline frames for an animation (`tests/test_notebook_animation.py` checks the same thing with a kernel and no browser) |
19+
20+
It runs in `docs.yml` after the site is built, as an informational step until it has
21+
passed on `main`. To run it yourself:
22+
23+
```bash
24+
pip install playwright && playwright install chromium
25+
pip install jupyterlite-core "jupyterlite-pyodide-kernel==0.6.1" jupyter-server ipympl
26+
RTB_PURE_WHEEL=1 python -m build --wheel --outdir docs/lite/pypi
27+
python docs/lite/browser_check/check_lite_in_browser.py
28+
```
29+
30+
`CHROMIUM_PATH` selects a Chromium executable, and `--screenshot` says where to save the
31+
page when a check fails. The run takes about two minutes: most of it is building the
32+
site and downloading Pyodide's packages in the browser.
33+
34+
The kernel version is pinned in `docs.yml` (`jupyterlite-pyodide-kernel==0.6.1`) for
35+
browsers without WebAssembly JSPI; see the comment there before changing it.
Lines changed: 284 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,284 @@
1+
#!/usr/bin/env python
2+
"""Check JupyterLite in a real browser: the toolbox installs, and plots and widgets work.
3+
4+
The Node/Pyodide check in ``../wasm_check/`` tests the install and the Python side
5+
without a browser. This one builds a small JupyterLite site that contains the wheel
6+
built from this checkout and one notebook, ``browser_check.ipynb``, opens it in
7+
Chromium, and runs the notebook, which does what the notebooks of the site do:
8+
9+
1. runs the generated bootstrap cell and prints the version of the toolbox,
10+
2. imports the toolbox and prints a hash of the source of ``PyPlot.py``,
11+
3. shows an ``ipywidgets`` slider,
12+
4. plots a robot with ``%matplotlib ipympl`` (an interactive figure),
13+
5. animates a trajectory with ``%matplotlib ipympl``.
14+
15+
It requires: the bootstrap line, the hash of the installed ``PyPlot.py`` to be that of
16+
the checkout (the site installs the wheel built with it, not the last release from
17+
PyPI, which is what a plain ``micropip.install`` does), the slider and the figure to be
18+
drawn, and the animation to show at least ``--min-frames`` different images while the
19+
cell is still running (an ``ipympl`` figure cannot update then, so the Toolbox pushes
20+
frames of its own).
21+
22+
Usage::
23+
24+
pip install playwright && playwright install chromium
25+
pip install jupyterlite-core "jupyterlite-pyodide-kernel==0.6.1" jupyter-server ipympl
26+
RTB_PURE_WHEEL=1 python -m build --wheel --outdir docs/lite/pypi
27+
python docs/lite/browser_check/check_lite_in_browser.py
28+
29+
``CHROMIUM_PATH`` selects a particular Chromium executable. A screenshot of the final
30+
page is saved on failure, to ``--screenshot``. Exits 0 if the checks pass, 1 if not.
31+
"""
32+
33+
from __future__ import annotations
34+
35+
import argparse
36+
import hashlib
37+
import json
38+
import os
39+
import shutil
40+
import subprocess
41+
import sys
42+
import tempfile
43+
import time
44+
from pathlib import Path
45+
46+
from playwright.sync_api import Error as PlaywrightError
47+
from playwright.sync_api import sync_playwright
48+
49+
HERE = Path(__file__).resolve().parent
50+
REPO = HERE.parents[2]
51+
NOTEBOOKS = REPO / "docs" / "notebooks"
52+
PYPLOT = REPO / "src" / "roboticstoolbox" / "backends" / "PyPlot" / "PyPlot.py"
53+
54+
BOOTSTRAP_TEXT = "Running in browser using RTB v"
55+
# the cells of the notebook, in order
56+
BOOTSTRAP, SETUP, WIDGET, FIGURE, ANIMATION = range(5)
57+
58+
CELLS = [
59+
None, # the generated bootstrap cell, see make_notebook
60+
"""%matplotlib ipympl
61+
import hashlib, importlib
62+
import roboticstoolbox as rtb
63+
module = importlib.import_module("roboticstoolbox.backends.PyPlot.PyPlot")
64+
print("PYPLOT_MD5", hashlib.md5(open(module.__file__, "rb").read()).hexdigest())
65+
robot = rtb.models.DH.Puma560()
66+
trajectory = rtb.jtraj(robot.qz, robot.qn, 100).q
67+
print("READY")""",
68+
"""import ipywidgets
69+
slider = ipywidgets.IntSlider(value=3, description="n")
70+
display(slider)""",
71+
"robot.plot(robot.qn);",
72+
"robot.plot(trajectory);",
73+
]
74+
75+
76+
class CheckFailed(Exception):
77+
"""A check failed; the message says which."""
78+
79+
80+
def make_notebook(path: Path) -> None:
81+
"""Write browser_check.ipynb, with the real generated bootstrap cell."""
82+
sys.path.insert(0, str(NOTEBOOKS))
83+
import sync_bootstrap
84+
85+
template = (NOTEBOOKS / "_rtb_nb_bootstrap.py").read_text(encoding="utf-8")
86+
sources = list(CELLS)
87+
sources[BOOTSTRAP] = "".join(sync_bootstrap.generated_source(template))
88+
nb = {
89+
"cells": [
90+
{
91+
"cell_type": "code",
92+
"execution_count": None,
93+
"id": f"cell{i}",
94+
"metadata": {},
95+
"outputs": [],
96+
"source": source,
97+
}
98+
for i, source in enumerate(sources)
99+
],
100+
"metadata": {
101+
"kernelspec": {
102+
"name": "python",
103+
"display_name": "Python (Pyodide)",
104+
"language": "python",
105+
}
106+
},
107+
"nbformat": 4,
108+
"nbformat_minor": 5,
109+
}
110+
path.write_text(json.dumps(nb), encoding="utf-8")
111+
112+
113+
def build_site(lite_dir: Path, work: Path) -> Path:
114+
"""Build a JupyterLite site with the wheel in lite_dir/pypi and the notebook."""
115+
source = work / "lite"
116+
(source / "files").mkdir(parents=True)
117+
for name in ("jupyter-lite.json", "jupyter_lite_config.json"):
118+
shutil.copy(lite_dir / name, source / name)
119+
shutil.copytree(lite_dir / "pypi", source / "pypi")
120+
if not list((source / "pypi").glob("roboticstoolbox_python-*.whl")):
121+
raise CheckFailed(f"no wheel in {lite_dir / 'pypi'}: build it first")
122+
make_notebook(source / "files" / "browser_check.ipynb")
123+
124+
out = work / "site"
125+
subprocess.run(
126+
[sys.executable, "-m", "jupyter", "lite", "build", "--output-dir", str(out)],
127+
cwd=source,
128+
check=True,
129+
capture_output=True,
130+
)
131+
# let the script drive JupyterLab through its commands
132+
config = out / "jupyter-lite.json"
133+
data = json.loads(config.read_text(encoding="utf-8"))
134+
data.setdefault("jupyter-config-data", {})["exposeAppInBrowser"] = True
135+
config.write_text(json.dumps(data), encoding="utf-8")
136+
return out
137+
138+
139+
def run_checks(page, timeout_s: float, min_frames: int) -> list[str]:
140+
"""Run the notebook in the page and check it; returns what passed."""
141+
passed = []
142+
cells = page.locator(".jp-NotebookPanel:not(.lm-mod-hidden) .jp-Cell")
143+
144+
page.wait_for_selector(
145+
".jp-NotebookPanel:not(.lm-mod-hidden) .jp-Notebook", timeout=90_000
146+
)
147+
page.wait_for_function("window.jupyterapp !== undefined", timeout=60_000)
148+
time.sleep(3)
149+
page.evaluate(
150+
"() => { window.jupyterapp.commands.execute('notebook:run-all-cells'); return 1 }"
151+
)
152+
153+
prompts = lambda: page.evaluate( # noqa: E731
154+
"[...document.querySelectorAll("
155+
"'.jp-NotebookPanel:not(.lm-mod-hidden) .jp-Cell .jp-InputPrompt')]"
156+
".map(e => e.textContent.trim())"
157+
)
158+
frames: list[str] = []
159+
deadline = time.monotonic() + timeout_s
160+
finished_at = None
161+
while time.monotonic() < deadline:
162+
time.sleep(1)
163+
state = prompts()
164+
if len(state) == len(CELLS) and "*" in state[ANIMATION]:
165+
# the animation is running: what is on the screen must keep changing
166+
area = cells.nth(ANIMATION).locator(".jp-OutputArea")
167+
try:
168+
if area.count() and area.first.is_visible():
169+
frames.append(
170+
hashlib.md5(area.first.screenshot(timeout=3000)).hexdigest()
171+
)
172+
except PlaywrightError:
173+
pass
174+
if len(state) == len(CELLS) and all(
175+
p and "*" not in p and p != "[ ]:" for p in state
176+
):
177+
finished_at = finished_at or time.monotonic()
178+
if time.monotonic() - finished_at > 3:
179+
break
180+
else:
181+
raise CheckFailed(f"the notebook did not finish within {timeout_s:.0f} s")
182+
183+
outputs = page.evaluate(
184+
"[...document.querySelectorAll('.jp-NotebookPanel:not(.lm-mod-hidden) .jp-Cell')]"
185+
".map(c => { const o = c.querySelector('.jp-OutputArea'); return o ? o.innerText : '' })"
186+
)
187+
for i, text in enumerate(outputs):
188+
if "Traceback" in text or "Error" in text.split("\n")[0]:
189+
raise CheckFailed(f"cell {i + 1} raised:\n{text[-1200:]}")
190+
191+
if BOOTSTRAP_TEXT not in outputs[BOOTSTRAP]:
192+
raise CheckFailed(
193+
f"no '{BOOTSTRAP_TEXT}' from the bootstrap cell:\n{outputs[BOOTSTRAP][-800:]}"
194+
)
195+
passed.append(
196+
next(line for line in outputs[BOOTSTRAP].splitlines() if BOOTSTRAP_TEXT in line)
197+
)
198+
199+
expected = hashlib.md5(PYPLOT.read_bytes()).hexdigest()
200+
reported = [
201+
line.split()[1] for line in outputs[SETUP].splitlines() if "PYPLOT_MD5" in line
202+
]
203+
if reported != [expected]:
204+
raise CheckFailed(
205+
"the toolbox in the browser is not the wheel built from this checkout "
206+
f"(PyPlot.py md5 {reported}, expected {expected}): the site installed "
207+
"the last release from PyPI instead of the wheel built with it"
208+
)
209+
passed.append("the installed toolbox is the wheel built with the site")
210+
211+
if cells.nth(WIDGET).locator(".widget-slider, .jupyter-widgets").count() == 0:
212+
raise CheckFailed("the ipywidgets slider was not drawn")
213+
passed.append("ipywidgets slider drawn")
214+
215+
if cells.nth(FIGURE).locator(".jupyter-matplotlib-canvas-container").count() == 0:
216+
raise CheckFailed("the ipympl figure of a single pose was not drawn")
217+
passed.append("ipympl figure drawn (interactive)")
218+
219+
distinct = len(set(frames))
220+
if distinct < min_frames:
221+
raise CheckFailed(
222+
f"the animation showed {distinct} different images in {len(frames)} "
223+
f"samples while it was running, wanted at least {min_frames}"
224+
)
225+
passed.append(f"animation: {distinct} different images in {len(frames)} samples")
226+
return passed
227+
228+
229+
def main() -> int:
230+
parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
231+
parser.add_argument("--lite-dir", type=Path, default=REPO / "docs" / "lite")
232+
parser.add_argument("--timeout", type=float, default=420, help="seconds to run")
233+
parser.add_argument("--min-frames", type=int, default=5)
234+
parser.add_argument("--screenshot", type=Path, default=Path("lite_check_failed.png"))
235+
args = parser.parse_args()
236+
237+
with tempfile.TemporaryDirectory() as tmp:
238+
site = build_site(args.lite_dir, Path(tmp))
239+
server = subprocess.Popen(
240+
[sys.executable, "-m", "http.server", "8890", "--directory", str(site)],
241+
stdout=subprocess.DEVNULL,
242+
stderr=subprocess.DEVNULL,
243+
)
244+
try:
245+
time.sleep(2)
246+
with sync_playwright() as p:
247+
browser = p.chromium.launch(
248+
executable_path=os.environ.get("CHROMIUM_PATH") or None
249+
)
250+
# a tall window, since JupyterLab draws only the cells that are visible
251+
page = browser.new_context(
252+
viewport={"width": 1300, "height": 5000}
253+
).new_page()
254+
errors: list[str] = []
255+
page.on("pageerror", lambda e: errors.append(str(e)[:200]))
256+
try:
257+
page.goto(
258+
"http://localhost:8890/lab/index.html"
259+
"?path=browser_check.ipynb&reset",
260+
wait_until="load",
261+
)
262+
passed = run_checks(page, args.timeout, args.min_frames)
263+
except (CheckFailed, PlaywrightError) as e:
264+
print(f"FAIL: {e}")
265+
for line in errors[:5]:
266+
print(f" page error: {line}")
267+
try:
268+
page.screenshot(path=str(args.screenshot))
269+
print(f"screenshot: {args.screenshot}")
270+
except PlaywrightError:
271+
pass
272+
return 1
273+
finally:
274+
browser.close()
275+
finally:
276+
server.terminate()
277+
278+
for line in passed:
279+
print(f"PASS: {line}")
280+
return 0
281+
282+
283+
if __name__ == "__main__":
284+
sys.exit(main())

0 commit comments

Comments
 (0)