|
| 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