@zsailer/jupyter-server-side-documents-conformance 0.0.0-stage → 0.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/runtime/tab.ts ADDED
@@ -0,0 +1,364 @@
1
+ import { expect, galata, IJupyterLabPageFixture, test } from '@jupyterlab/galata';
2
+ import type { Browser, BrowserContext, Page } from '@playwright/test';
3
+ import * as nodePath from 'node:path';
4
+ import { keepLook, Recorder } from './recording';
5
+ import { prepareNetwork, setNetwork } from './network';
6
+ import { sourceText } from './cells';
7
+
8
+ export interface TabEnv {
9
+ browser: Browser;
10
+ baseURL: string;
11
+ waitForApplication: (page: Page, helpers: any) => Promise<void>;
12
+ /** The folder on the server the story works in: a tab opens JupyterLab there (Galata opens `/lab/tree/<dir>`). */
13
+ dir: string;
14
+ /** Keeps a video of every tab, and when each step happened. */
15
+ recorder: Recorder;
16
+ }
17
+
18
+ /** The size of every tab's browser, and of its video. */
19
+ const VIEW = { width: 1280, height: 720 };
20
+
21
+ /** Waits that every test shares. Milliseconds. */
22
+ export const WAIT = {
23
+ /** How long a tab may take to show what it should (a sync, a reconnect). */
24
+ eventually: Number(process.env.COMPLIANCE_TIMEOUT_MS ?? 20000),
25
+ /** How long the file may take to be saved. */
26
+ save: Number(process.env.COMPLIANCE_SAVE_TIMEOUT_MS ?? 40000),
27
+ /** How long a notebook must stay as it is before it counts as settled (catches a late duplicate). */
28
+ stable: Number(process.env.COMPLIANCE_STABLE_MS ?? 1500)
29
+ };
30
+
31
+ /**
32
+ * Whether a JupyterLab page is ready to be driven: its splash screen is gone and the application has restored.
33
+ *
34
+ * Galata's own check also waits for the Launcher tab to be active, which a tab that goes straight to a notebook neither
35
+ * needs nor always gets.
36
+ */
37
+ async function waitForLab(page: Page): Promise<void> {
38
+ await page.locator('#jupyterlab-splash').waitFor({ state: 'detached', timeout: WAIT.eventually });
39
+ await page.waitForFunction(() => Boolean((window as any).jupyterapp), undefined, { timeout: WAIT.eventually });
40
+ await page.evaluate(async () => {
41
+ await (window as any).jupyterapp.restored;
42
+ });
43
+ }
44
+
45
+ /** When a tab cannot be set up, say what it looked like: a picture and the page as text, kept in the results folder. */
46
+ async function explain(page: Page | null, name: string, dir: string, extra: string): Promise<void> {
47
+ if (page) {
48
+ await keepLook(dir, name, 'could not be set up', page as any, extra);
49
+ }
50
+ }
51
+
52
+ /**
53
+ * One browser tab with JupyterLab in it: its own browser context, so it has its own connection (it can go offline on
54
+ * its own) and its own storage, the way another person's browser would.
55
+ *
56
+ * It does what a person does, with real keystrokes, and reports what the person would see.
57
+ */
58
+ export class Tab {
59
+ page: IJupyterLabPageFixture | null = null;
60
+ private context: BrowserContext | null = null;
61
+ private lead: Page | null = null;
62
+ private startedAt = 0;
63
+ private opened = 0;
64
+ private offline = false;
65
+ /** What the browser reported while the tab was being set up, for when it cannot be. */
66
+ private events: string[] = [];
67
+ private askedToReconnect = false;
68
+
69
+ constructor(
70
+ readonly name: string,
71
+ private readonly env: TabEnv,
72
+ /** The path of the notebook, on the server. */
73
+ private readonly path: string,
74
+ /** Whether to keep a video of this tab (a fresh tab opened only to look is not worth one). */
75
+ private readonly record = true
76
+ ) {}
77
+
78
+ get isOpen(): boolean {
79
+ return this.page !== null;
80
+ }
81
+
82
+ private get p(): IJupyterLabPageFixture {
83
+ if (!this.page) {
84
+ throw new Error(`The tab "${this.name}" is not open`);
85
+ }
86
+ return this.page;
87
+ }
88
+
89
+ /** Open JupyterLab in a new browser, and the notebook in it. */
90
+ async open(): Promise<void> {
91
+ try {
92
+ // The browser is made here, not by Galata, so that it can be recorded: Playwright films only the pages it makes.
93
+ this.startedAt = Date.now();
94
+ this.opened++;
95
+ this.context = await this.env.browser.newContext(
96
+ this.record
97
+ ? { viewport: VIEW, recordVideo: { dir: nodePath.join(this.env.recorder.dir, 'videos'), size: VIEW } }
98
+ : { viewport: VIEW }
99
+ );
100
+ await prepareNetwork(this.context);
101
+ this.lead = await this.context.newPage();
102
+ this.watch(this.lead);
103
+ const page = await galata.initTestPage(
104
+ '/lab',
105
+ true,
106
+ this.env.baseURL,
107
+ true,
108
+ galata.DEFAULT_SETTINGS,
109
+ true,
110
+ true,
111
+ this.lead,
112
+ new Map(),
113
+ new Map(),
114
+ this.env.dir,
115
+ async p => waitForLab(p),
116
+ new Map(),
117
+ true
118
+ );
119
+ this.page = page;
120
+ await page.evaluate(async (p: string) => {
121
+ await (window as any).jupyterapp.commands.execute('docmanager:open', { path: p });
122
+ }, this.path);
123
+ await dismissKernelDialogIfPresent(page);
124
+ await expect
125
+ .poll(async () => (await this.cells())?.length ?? 0, {
126
+ timeout: WAIT.eventually,
127
+ message: `${this.name}: the notebook never appeared`
128
+ })
129
+ .toBeGreaterThan(0);
130
+ } catch (e) {
131
+ await explain(this.lead, this.name, this.env.recorder.dir, await this.report());
132
+ throw e;
133
+ }
134
+ }
135
+
136
+ private watch(page: Page): void {
137
+ const at = () => ((Date.now() - this.startedAt) / 1000).toFixed(1).padStart(5);
138
+ const keep = (line: string) => this.events.length < 300 && this.events.push(`${at()}s ${line}`);
139
+ page.on('console', m => ['error', 'warning'].includes(m.type()) && keep(`console.${m.type()}: ${m.text().slice(0, 300)}`));
140
+ page.on('pageerror', e => keep(`pageerror: ${String(e).slice(0, 300)}`));
141
+ page.on('requestfailed', r => keep(`request failed: ${r.method()} ${r.url().slice(0, 160)} (${r.failure()?.errorText})`));
142
+ page.on('response', r => r.status() >= 400 && keep(`HTTP ${r.status()}: ${r.url().slice(0, 160)}`));
143
+ page.on('requestfinished', r => {
144
+ const timing = r.timing();
145
+ const took = timing.responseEnd - timing.startTime;
146
+ if (took > 2000) {
147
+ keep(`slow request (${(took / 1000).toFixed(1)} s): ${r.method()} ${r.url().slice(0, 140)}`);
148
+ }
149
+ });
150
+ page.on('framenavigated', f => f === page.mainFrame() && keep(`navigated: ${f.url().slice(0, 160)}`));
151
+ }
152
+
153
+ /** What the browser said while the tab was loading, and whether the server answers right now. */
154
+ private async report(): Promise<string> {
155
+ let ping: string;
156
+ const began = Date.now();
157
+ try {
158
+ const res = await fetch(`${this.env.baseURL}/api/status`, { signal: AbortSignal.timeout(5000) });
159
+ ping = `the server answers /api/status: HTTP ${res.status} in ${Date.now() - began} ms`;
160
+ } catch (e) {
161
+ ping = `the server does NOT answer /api/status within 5 s: ${String(e)}`;
162
+ }
163
+ return [`${this.name}: opened ${((Date.now() - this.startedAt) / 1000).toFixed(1)} s ago, at ${this.lead?.url() ?? '?'}`, ping, '', ...this.events].join('\n');
164
+ }
165
+
166
+ /** The person closes the tab: the connection goes with it. The video is complete once it has closed. */
167
+ async close(): Promise<void> {
168
+ if (!this.context) {
169
+ return;
170
+ }
171
+ const video = this.record ? this.lead?.video() : null;
172
+ await this.context.close().catch(() => undefined);
173
+ if (this.record) {
174
+ const file = video ? await video.path().catch(() => null) : null;
175
+ this.env.recorder.tabs.push({ name: this.opened > 1 ? `${this.name} (${this.opened})` : this.name, startedAt: this.startedAt, file });
176
+ }
177
+ this.context = null;
178
+ this.lead = null;
179
+ this.page = null;
180
+ }
181
+
182
+ /** The connection drops (a laptop lid closed). The tab keeps working on what it has. */
183
+ async goOffline(): Promise<void> {
184
+ await setNetwork(this.p.context(), true);
185
+ this.offline = true;
186
+ }
187
+
188
+ /** The connection comes back. */
189
+ async goOnline(): Promise<void> {
190
+ await setNetwork(this.p.context(), false);
191
+ this.offline = false;
192
+ await this.clickReconnectIfAsked(3000);
193
+ }
194
+
195
+ /**
196
+ * After enough failed attempts JupyterLab stops reconnecting by itself and asks the person to click "Reconnect". A
197
+ * person who is back online does; so does the test, and it says so, because that is something a person would have seen.
198
+ */
199
+ async clickReconnectIfAsked(waitMs = 0, evenOffline = false): Promise<boolean> {
200
+ if (!this.page || (this.offline && !evenOffline)) {
201
+ return false;
202
+ }
203
+ let asked = 'Reconnect';
204
+ const dialog = this.page.locator('.jp-Dialog', { hasText: /unable to reconnect|connection error|cannot open/i });
205
+ try {
206
+ if (waitMs) {
207
+ await dialog.first().waitFor({ state: 'visible', timeout: waitMs });
208
+ } else if ((await dialog.count()) === 0) {
209
+ return false;
210
+ }
211
+ // "Cannot open Failed to fetch" comes up when the tab tries to fetch the file while cut off; a person closes it
212
+ asked = ((await dialog.first().innerText()) || '').toLowerCase().includes('cannot open') ? 'Close' : 'Reconnect';
213
+ // the error dialog's only button is "Close", which is not the accept button
214
+ const button = asked === 'Close' ? '.jp-Dialog-button' : '.jp-mod-accept';
215
+ await dialog.locator(button).first().click({ timeout: 3000 });
216
+ } catch {
217
+ return false;
218
+ }
219
+ if (!this.askedToReconnect) {
220
+ this.askedToReconnect = true;
221
+ this.env.recorder.note(`${this.name}: asked the person to click “${asked}”, and they did`);
222
+ }
223
+ return true;
224
+ }
225
+
226
+ /**
227
+ * Do something with the keyboard and mouse the way a person does when a dialog may come up in the middle of it: the
228
+ * "Connection Error" dialog blocks the notebook after a few failed reconnects (about 4 s into an outage), and a person
229
+ * who wants to carry on clicks it away. Without this a click waits behind the dialog.
230
+ */
231
+ private async asPerson<T>(act: () => Promise<T>): Promise<T> {
232
+ let done = false;
233
+ const watcher = (async () => {
234
+ while (!done) {
235
+ await this.clickReconnectIfAsked(0, true);
236
+ await new Promise(r => setTimeout(r, 300));
237
+ }
238
+ })();
239
+ try {
240
+ return await act();
241
+ } finally {
242
+ done = true;
243
+ await watcher;
244
+ }
245
+ }
246
+
247
+ /** The sources of the cells the tab shows, or null if the notebook is not open in it. */
248
+ async cells(): Promise<string[] | null> {
249
+ if (!this.page) {
250
+ return null;
251
+ }
252
+ await this.clickReconnectIfAsked();
253
+ const raw = await this.page.evaluate((p: string) => {
254
+ const app = (window as any).jupyterapp;
255
+ for (const widget of app.shell.widgets('main')) {
256
+ const context = (widget as any).context;
257
+ if (context?.path === p && context.model?.sharedModel) {
258
+ return context.model.sharedModel.toJSON().cells.map((c: any) => c.source);
259
+ }
260
+ }
261
+ return null;
262
+ }, this.path);
263
+ return raw === null ? null : raw.map(sourceText);
264
+ }
265
+
266
+ /** Type `text` at the end of cell `index`, key by key. */
267
+ async type(index: number, text: string): Promise<void> {
268
+ return this.asPerson(() => this.typeNow(index, text));
269
+ }
270
+
271
+ private async typeNow(index: number, text: string): Promise<void> {
272
+ const page = this.p;
273
+ await page.notebook.enterCellEditingMode(index);
274
+ await page.keyboard.press('End');
275
+ await page.keyboard.type(text);
276
+ await page.notebook.leaveCellEditingMode(index);
277
+ }
278
+
279
+ /** Replace everything in cell `index` with `text`. */
280
+ async rewrite(index: number, text: string): Promise<void> {
281
+ return this.asPerson(() => this.rewriteNow(index, text));
282
+ }
283
+
284
+ private async rewriteNow(index: number, text: string): Promise<void> {
285
+ const page = this.p;
286
+ await page.notebook.enterCellEditingMode(index);
287
+ // select all: Control+A moves the cursor to the start of the line on a Mac, so ask for the key the platform uses
288
+ await page.keyboard.press('ControlOrMeta+a');
289
+ await page.keyboard.type(text);
290
+ await page.notebook.leaveCellEditingMode(index);
291
+ }
292
+
293
+ /** Add a cell so that it ends up at `index`, and type `text` into it. */
294
+ async addCell(index: number, text: string): Promise<void> {
295
+ return this.asPerson(() => this.addCellNow(index, text));
296
+ }
297
+
298
+ private async addCellNow(index: number, text: string): Promise<void> {
299
+ const page = this.p;
300
+ const before = (await page.notebook.getCellCount()) ?? 0;
301
+ index = Math.min(index, before); // a tab that has not yet seen every cell adds at the end of what it has
302
+ if (index === 0) {
303
+ await page.notebook.selectCells(0);
304
+ await this.command('notebook:insert-cell-above');
305
+ } else {
306
+ await page.notebook.selectCells(Math.min(index - 1, before - 1));
307
+ await this.command('notebook:insert-cell-below');
308
+ }
309
+ await expect.poll(async () => page.notebook.getCellCount()).toBe(before + 1);
310
+ await page.notebook.setCell(index, 'code', text);
311
+ }
312
+
313
+ /** Delete cell `index`. */
314
+ async deleteCell(index: number): Promise<void> {
315
+ return this.asPerson(() => this.deleteCellNow(index));
316
+ }
317
+
318
+ private async deleteCellNow(index: number): Promise<void> {
319
+ const page = this.p;
320
+ const before = await page.notebook.getCellCount();
321
+ await page.notebook.selectCells(index);
322
+ await page.notebook.deleteCells();
323
+ await expect.poll(async () => page.notebook.getCellCount()).toBe(before - 1);
324
+ }
325
+
326
+ /** Move cell `from` so that it ends up at `to`. */
327
+ async moveCell(from: number, to: number): Promise<void> {
328
+ return this.asPerson(() => this.moveCellNow(from, to));
329
+ }
330
+
331
+ private async moveCellNow(from: number, to: number): Promise<void> {
332
+ const page = this.p;
333
+ await page.notebook.selectCells(from);
334
+ const command = to > from ? 'notebook:move-cell-down' : 'notebook:move-cell-up';
335
+ for (let i = 0; i < Math.abs(to - from); i++) {
336
+ await this.command(command);
337
+ }
338
+ }
339
+
340
+ private async command(id: string): Promise<void> {
341
+ await this.p.evaluate(async (c: string) => {
342
+ await (window as any).jupyterapp.commands.execute(c);
343
+ }, id);
344
+ }
345
+ }
346
+
347
+ /**
348
+ * Dismiss the "Select Kernel" dialog that opens with a notebook, choosing "No Kernel": these tests are about the
349
+ * document, not about running code. Nothing happens if the dialog does not appear.
350
+ */
351
+ export async function dismissKernelDialogIfPresent(page: IJupyterLabPageFixture): Promise<void> {
352
+ const dialog = page.locator('.jp-Dialog');
353
+ try {
354
+ await dialog.waitFor({ state: 'visible', timeout: 10000 });
355
+ } catch {
356
+ return;
357
+ }
358
+ const combobox = dialog.getByRole('combobox');
359
+ if (await combobox.count()) {
360
+ await combobox.selectOption('null').catch(() => undefined);
361
+ }
362
+ await dialog.locator('.jp-mod-accept').click();
363
+ await dialog.waitFor({ state: 'hidden', timeout: 10000 }).catch(() => undefined);
364
+ }
@@ -0,0 +1,63 @@
1
+ /**
2
+ * What a backend can do for the compliance tests, beyond what any JupyterLab with real-time collaboration offers.
3
+ *
4
+ * Every story states what it needs (from the kinds of its steps). A story whose needs the adapter does not meet is
5
+ * skipped, with the missing capabilities in the reason, so a report says what was verified and what was not.
6
+ */
7
+ export type Capability =
8
+ /** Read and write notebooks through the Contents API. Every adapter has this. */
9
+ | 'contents'
10
+ /** Read the cells of the server's own live copy of a notebook (otherwise a fresh tab is opened to see it). */
11
+ | 'serverState'
12
+ /** Make the server let go of a notebook (saving it); the next client rebuilds it from the file. */
13
+ | 'releaseRoom'
14
+ /** Kill the server without letting it save, and start it again. */
15
+ | 'crashServer'
16
+ /** Change the notebook file the way something outside Jupyter does (git, a sync tool, an editor, a restore). */
17
+ | 'fileSystem'
18
+ /** Lose or delay a message on the wire between a tab and the server. */
19
+ | 'wireFaults'
20
+ /** Let an AI agent edit the notebook, through the server or through the file. */
21
+ | 'agent'
22
+ /** The server keeps a history record of each notebook next to the file. */
23
+ | 'historyRecord';
24
+
25
+ /** What the tests can do whatever the adapter: Playwright toggles the network of a tab. */
26
+ export const ALWAYS: ReadonlyArray<string> = ['network'];
27
+
28
+ /** How a cell is expected to read. A string is an exact match (surrounding whitespace ignored). */
29
+ export type Expect =
30
+ | string
31
+ | { /** the cell starts with `base` and holds every part, in any order (typing from two people) */ base: string; parts: string[] }
32
+ | { /** the cell holds every one of these */ contains: string[] };
33
+
34
+ /** What a story says about itself. Generated; see compliance/generate.py. */
35
+ export interface StoryMeta {
36
+ id: string;
37
+ group: string;
38
+ title: string;
39
+ /** What the story needs from the backend, beyond the always-available. */
40
+ requires: Capability[];
41
+ /** The story's answer is still an open question: see `decisions`. */
42
+ needsAlignment?: boolean;
43
+ /** The case is only proposed: a backend that does not meet it is reported, and the test does not fail. */
44
+ proposed?: boolean;
45
+ /** Applies only if the backend does something optional (e.g. keeps a history record). */
46
+ appliesIf?: string[];
47
+ /** The cells the notebook file holds at the start (names; see cells.ts). */
48
+ /** Whether the order of the cells at the end is part of the answer. */
49
+ ordered?: boolean;
50
+ /** Something inside the server that a person can neither cause nor see: the story is skipped, with this reason. */
51
+ internal?: string;
52
+ /** Notes the generator could not turn into an exact expectation: the story is checked more loosely. */
53
+ loose?: string[];
54
+ }
55
+
56
+ /** What every copy must hold at the end, per lane. */
57
+ export type Ends = Partial<Record<'file' | 'server' | string, Expect[]>>;
58
+
59
+ /** One way a story may end: the proposed answer, or an alternative the storyboard names. */
60
+ export interface Ending {
61
+ label: string;
62
+ ends: Ends;
63
+ }
@@ -0,0 +1,100 @@
1
+ #!/usr/bin/env python3
2
+ """Summarize a run of the compliance tests: one line per story, and what the open questions came out as.
3
+
4
+ python3 -I compliance/scripts/summarize.py [test-results folder]
5
+
6
+ Reads what Playwright left in test-results/ (a folder per story that ran; an error-context.md in those that failed) and
7
+ stories.json (every story, and what it needs). A story with no folder was skipped.
8
+ """
9
+ from __future__ import annotations
10
+
11
+ import json
12
+ import re
13
+ import sys
14
+ from pathlib import Path
15
+
16
+ HERE = Path(__file__).resolve().parent
17
+ COMPLIANCE = HERE.parent
18
+ RESULTS = Path(sys.argv[1]) if len(sys.argv) > 1 else COMPLIANCE / "test-results"
19
+
20
+
21
+ def reason(folder: Path) -> str:
22
+ text = (folder / "error-context.md").read_text(encoding="utf-8", errors="replace")
23
+ m = re.search(r"# Error details\s+```\s*(.*?)```", text, re.S)
24
+ body = (m.group(1) if m else "").strip()
25
+ lines = [line.strip() for line in body.splitlines() if line.strip()]
26
+ if not lines:
27
+ return "failed"
28
+ first = re.sub(r"^Error:\s*", "", lines[0])
29
+ if first.startswith("step ") and len(lines) > 1: # "step 6. Tab B ..." then the reason
30
+ second = re.sub(r"^Error:\s*", "", lines[1])
31
+ first = f"{first} — {second}"
32
+ return first[:150]
33
+
34
+
35
+ def main() -> None:
36
+ stories = json.loads((COMPLIANCE / "stories.json").read_text())
37
+ folders = {}
38
+ for d in RESULTS.glob("*"):
39
+ m = re.match(r"generated-[a-z]+-([A-Z]+[0-9]*)-", d.name)
40
+ if d.is_dir() and m:
41
+ folders[m.group(1)] = d
42
+ adapter_file = RESULTS / "adapter.json"
43
+ has = set(json.loads(adapter_file.read_text())["capabilities"]) if adapter_file.exists() else None
44
+ passed = failed = missed = 0
45
+ skipped: dict[str, list[str]] = {}
46
+ rows = []
47
+ for s in stories:
48
+ folder = folders.get(s["id"])
49
+ if folder is None:
50
+ missing = [r for r in s["requires"] if has is not None and r not in has]
51
+ if s["internal"]:
52
+ why = "not checkable from the user's side"
53
+ elif has is not None and not missing:
54
+ why = "not selected in this run"
55
+ else:
56
+ why = "needs " + ", ".join(missing or s["requires"])
57
+ skipped.setdefault(why, []).append(s["id"])
58
+ continue
59
+ if (folder / "not-met.txt").exists(): # a proposed case the backend does not meet: reported, not failed
60
+ missed += 1
61
+ line = next((l for l in (folder / "not-met.txt").read_text().splitlines() if l.strip()), "")
62
+ rows.append((s["id"], "miss", line.strip()[:150], s["needsAlignment"]))
63
+ elif (folder / "error-context.md").exists():
64
+ failed += 1
65
+ rows.append((s["id"], "FAIL", reason(folder), s["needsAlignment"]))
66
+ else:
67
+ passed += 1
68
+ rows.append((s["id"], "ok", "", s["needsAlignment"]))
69
+ print(f"\n{len(stories)} stories: {passed} passed, {failed} failed, {missed} proposed cases not met, {sum(len(v) for v in skipped.values())} skipped\n")
70
+ for sid, status, why, open_ in rows:
71
+ print(f" {sid:<4} {status:<4} {'?' if open_ else ' '} {why}")
72
+ print("\n ? = the storyboard still asks a question about this one")
73
+ if missed:
74
+ print(" miss = a proposed case this backend does not meet yet (reported, not failed)")
75
+ print("\nSkipped:")
76
+ for why, ids in sorted(skipped.items(), key=lambda kv: -len(kv[1])):
77
+ print(f" {len(ids):>2} {why}: {', '.join(ids)}")
78
+ probe = RESULTS / "probe.txt"
79
+ if probe.exists():
80
+ print("\nProbe:")
81
+ for line in probe.read_text().splitlines():
82
+ print(" " + line)
83
+ notes = RESULTS / "notes.jsonl"
84
+ if notes.exists():
85
+ print("\nWhat a person would have noticed:")
86
+ for line in notes.read_text().splitlines():
87
+ r = json.loads(line)
88
+ print(f" {r['id']:<4} {r['note']}")
89
+ verdicts = RESULTS / "implements.jsonl"
90
+ if verdicts.exists():
91
+ print("\nOpen questions in the storyboards, and what this backend does:")
92
+ for line in verdicts.read_text().splitlines():
93
+ r = json.loads(line)
94
+ print(f" {r['id']:<4} {r['title']}")
95
+ for v in r["verdict"]:
96
+ print(f" {v}")
97
+
98
+
99
+ if __name__ == "__main__":
100
+ main()
@@ -0,0 +1,48 @@
1
+ """Jupyter Server configuration for the conformance tests.
2
+
3
+ !! Never use this configuration in production: it opens the server to anyone who can reach it, and it gives the page
4
+ access to JupyterLab's JavaScript objects through the global `window`.
5
+
6
+ It is what the tests need of any Jupyter Server based backend:
7
+
8
+ - the server is set up the way JupyterLab's own UI tests set it up (no login, the app exposed to the page);
9
+ - when CONFORMANCE_CONTROL names a module in this folder, that module is loaded as a server extension. It is the
10
+ backend's side of the control contract (docs/backend-contract.md), and it is what lets a test make the server let go
11
+ of a notebook;
12
+ - frontend extensions that open a blocking modal on load can be switched off: list them in CONFORMANCE_DISABLED_EXTENSIONS
13
+ (comma-separated labextension names, or a scope such as `@my-org` to switch off every extension in it).
14
+ """
15
+ import json
16
+ import os
17
+ import sys
18
+ import tempfile
19
+ from pathlib import Path
20
+
21
+ from jupyter_core.paths import jupyter_path
22
+ from jupyterlab.galata import configure_jupyter_server
23
+
24
+ configure_jupyter_server(c) # noqa: F821 - `c` is the config object Jupyter provides
25
+
26
+ # CI containers run as root, which Jupyter Server refuses by default.
27
+ c.ServerApp.allow_root = True # noqa: F821
28
+
29
+ control = os.environ.get("CONFORMANCE_CONTROL")
30
+ if control:
31
+ sys.path.insert(0, str(Path(__file__).resolve().parent))
32
+ c.ServerApp.jpserver_extensions = {control: True} # noqa: F821
33
+
34
+ # JupyterLab reads labconfig/page_config.json from the config path on each page load, so a generated one is put first.
35
+ disabled = {}
36
+ for entry in filter(None, (e.strip() for e in os.environ.get("CONFORMANCE_DISABLED_EXTENSIONS", "").split(","))):
37
+ if entry.startswith("@") and "/" not in entry:
38
+ for root in jupyter_path("labextensions"):
39
+ scope = Path(root) / entry
40
+ if scope.is_dir():
41
+ disabled.update({f"{entry}/{p.name}": True for p in scope.iterdir()})
42
+ else:
43
+ disabled[entry] = True
44
+ if disabled:
45
+ config_dir = Path(tempfile.mkdtemp(prefix="conformance-config-"))
46
+ (config_dir / "labconfig").mkdir()
47
+ (config_dir / "labconfig" / "page_config.json").write_text(json.dumps({"disabledExtensions": disabled}))
48
+ os.environ["JUPYTER_CONFIG_PATH"] = os.pathsep.join(filter(None, [str(config_dir), os.environ.get("JUPYTER_CONFIG_PATH")]))
@@ -0,0 +1,91 @@
1
+ """The backend's side of the conformance control contract, for jupyter-server-documents.
2
+
3
+ !! Test-only. It lets any authenticated client destroy live document rooms: load it only through
4
+ server/conformance_config.py (CONFORMANCE_CONTROL=jsd_control), never in production.
5
+
6
+ The contract is in docs/backend-contract.md. Three endpoints, under the server's base URL:
7
+
8
+ GET /conformance/capabilities what this backend can do for a test
9
+ GET /conformance/room?path=<path> the cells of the server's live copy of a notebook; 404 if it holds none
10
+ POST /conformance/release-room?path=<path> the server saves the notebook and lets go of it; the next client to
11
+ connect makes it build the notebook again from the file
12
+
13
+ This file knows how jupyter-server-documents keeps its rooms (`yroom_manager`, `file_id_manager`), so it is the part
14
+ to update when that changes.
15
+ """
16
+ import json
17
+
18
+ import tornado
19
+ from jupyter_server.base.handlers import APIHandler
20
+ from jupyter_server.utils import url_path_join
21
+
22
+ BACKEND = "jsd"
23
+ CAPABILITIES = ["serverState", "releaseRoom"]
24
+
25
+
26
+ def cells_of(source):
27
+ """The sources of the cells of a notebook given as a JSON string or as a dict, one string per cell."""
28
+ notebook = json.loads(source) if isinstance(source, str) else source
29
+ cells = []
30
+ for cell in notebook.get("cells", []):
31
+ text = cell.get("source", "")
32
+ cells.append("".join(text) if isinstance(text, list) else text)
33
+ return cells
34
+
35
+
36
+ def rooms_for_path(settings, path):
37
+ """The open document rooms of a file. Read-only: it never creates a room."""
38
+ fid = settings["file_id_manager"].get_id(path)
39
+ if fid is None:
40
+ return []
41
+ manager = settings["yroom_manager"]
42
+ return [room for room in manager.list_document_rooms() if room.room_id.endswith(f":{fid}")]
43
+
44
+
45
+ class CapabilitiesHandler(APIHandler):
46
+ @tornado.web.authenticated
47
+ async def get(self):
48
+ self.finish(json.dumps({"backend": BACKEND, "capabilities": CAPABILITIES}))
49
+
50
+
51
+ class RoomHandler(APIHandler):
52
+ @tornado.web.authenticated
53
+ async def get(self):
54
+ path = self.get_argument("path")
55
+ rooms = rooms_for_path(self.settings, path)
56
+ if not rooms:
57
+ raise tornado.web.HTTPError(404, f"No open room for path '{path}'.")
58
+ ydoc = getattr(rooms[0], "_jupyter_ydoc", None)
59
+ if ydoc is None:
60
+ raise tornado.web.HTTPError(404, f"The room for '{path}' holds no notebook yet.")
61
+ self.finish(json.dumps({"cells": cells_of(ydoc.source)}))
62
+
63
+
64
+ class ReleaseRoomHandler(APIHandler):
65
+ @tornado.web.authenticated
66
+ async def post(self):
67
+ path = self.get_argument("path")
68
+ manager = self.settings["yroom_manager"]
69
+ for room in rooms_for_path(self.settings, path):
70
+ # delete_room() stops the room (clients are closed with code 1001) and waits for the final save before it
71
+ # removes the room, so the content is on disk and is read again when a client next connects
72
+ await manager.delete_room(room.room_id)
73
+ self.finish(json.dumps({}))
74
+
75
+
76
+ def _jupyter_server_extension_points():
77
+ return [{"module": "jsd_control"}]
78
+
79
+
80
+ def _load_jupyter_server_extension(server_app):
81
+ web_app = server_app.web_app
82
+ base_url = web_app.settings["base_url"]
83
+ web_app.add_handlers(
84
+ ".*$",
85
+ [
86
+ (url_path_join(base_url, "conformance", "capabilities"), CapabilitiesHandler),
87
+ (url_path_join(base_url, "conformance", "room"), RoomHandler),
88
+ (url_path_join(base_url, "conformance", "release-room"), ReleaseRoomHandler),
89
+ ],
90
+ )
91
+ server_app.log.info("jsd_control (conformance test extension) loaded")