@jupyterlab/testing 4.0.0-alpha.19 → 4.0.0-alpha.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jupyterlab/testing",
-  "version": "4.0.0-alpha.19",
+  "version": "4.0.0-alpha.20",
   "description": "JupyterLab basic testing utilities.",
   "homepage": "https://github.com/jupyterlab/jupyterlab",
   "bugs": {
@@ -18,7 +18,8 @@
     "lib": "lib/"
   },
   "files": [
-    "lib/**/*.{d.ts,js,js.map,json}"
+    "lib/**/*.{d.ts,js,js.map,json}",
+    "src/**/*.{ts,tsx}"
   ],
   "scripts": {
     "build": "tsc -b",
@@ -34,9 +35,9 @@
   "dependencies": {
     "@babel/core": "^7.10.2",
     "@babel/preset-env": "^7.10.2",
-    "@jupyterlab/coreutils": "^6.0.0-alpha.19",
-    "@lumino/coreutils": "^2.0.0-beta.0",
-    "@lumino/signaling": "^2.0.0-beta.1",
+    "@jupyterlab/coreutils": "^6.0.0-alpha.20",
+    "@lumino/coreutils": "^2.0.0-rc.0",
+    "@lumino/signaling": "^2.0.0-rc.0",
     "child_process": "~1.0.2",
     "deepmerge": "^4.2.2",
     "fs-extra": "^10.1.0",
@@ -53,7 +54,7 @@
     "@types/node": "^18.11.18",
     "@types/node-fetch": "^2.6.2",
     "rimraf": "~3.0.0",
-    "typescript": "~4.7.3"
+    "typescript": "~5.0.0-beta"
   },
   "publishConfig": {
     "access": "public"

package/src/babel-config.ts

@@ -0,0 +1,19 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+const babelConfig = {
+  presets: [
+    [
+      '@babel/preset-env',
+      {
+        targets: {
+          node: 'current'
+        }
+      }
+    ]
+  ]
+};
+
+export default babelConfig;

package/src/common.ts

@@ -0,0 +1,248 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+import { simulate } from 'simulate-event';
+
+import { PromiseDelegate } from '@lumino/coreutils';
+
+import { ISignal, Signal } from '@lumino/signaling';
+
+import { sleep } from '@jupyterlab/coreutils/lib/testutils';
+
+export { sleep } from '@jupyterlab/coreutils/lib/testutils';
+
+/**
+ * Test a single emission from a signal.
+ *
+ * @param signal - The signal we are listening to.
+ * @param find - An optional function to determine which emission to test,
+ * defaulting to the first emission.
+ * @param test - An optional function which contains the tests for the emission, and should throw an error if the tests fail.
+ * @param value - An optional value that the promise resolves to if the test is
+ * successful.
+ *
+ * @returns a promise that rejects if the function throws an error (e.g., if an
+ * expect test doesn't pass), and resolves otherwise.
+ *
+ * #### Notes
+ * The first emission for which the find function returns true will be tested in
+ * the test function. If the find function is not given, the first signal
+ * emission will be tested.
+ *
+ * You can test to see if any signal comes which matches a criteria by just
+ * giving a find function. You can test the very first signal by just giving a
+ * test function. And you can test the first signal matching the find criteria
+ * by giving both.
+ *
+ * The reason this function is asynchronous is so that the thing causing the
+ * signal emission (such as a websocket message) can be asynchronous.
+ */
+export async function testEmission<T, U, V>(
+  signal: ISignal<T, U>,
+  options: {
+    find?: (a: T, b: U) => boolean;
+    test?: (a: T, b: U) => void;
+    value?: V;
+  } = {}
+): Promise<V | undefined> {
+  const done = new PromiseDelegate<V | undefined>();
+  const object = {};
+  signal.connect((sender: T, args: U) => {
+    if (options.find?.(sender, args) ?? true) {
+      try {
+        Signal.disconnectReceiver(object);
+        if (options.test) {
+          options.test(sender, args);
+        }
+      } catch (e) {
+        done.reject(e);
+      }
+      done.resolve(options.value ?? undefined);
+    }
+  }, object);
+  return done.promise;
+}
+
+/**
+ * Expect a failure on a promise with the given message.
+ */
+export async function expectFailure(
+  promise: Promise<any>,
+  message?: string
+): Promise<void> {
+  let called = false;
+  try {
+    await promise;
+    called = true;
+  } catch (err) {
+    if (message && err.message.indexOf(message) === -1) {
+      throw Error(`Error "${message}" not in: "${err.message}"`);
+    }
+  }
+  if (called) {
+    throw Error(`Failure was not triggered, message was: ${message}`);
+  }
+}
+
+/**
+ * Do something in the future ensuring total ordering with respect to promises.
+ */
+export async function doLater(cb: () => void): Promise<void> {
+  await Promise.resolve(void 0);
+  cb();
+}
+
+/**
+ * Convert a signal into an array of promises.
+ *
+ * @param signal - The signal we are listening to.
+ * @param numberValues - The number of values to store.
+ *
+ * @returns a Promise that resolves with an array of `(sender, args)` pairs.
+ */
+export function signalToPromises<T, U>(
+  signal: ISignal<T, U>,
+  numberValues: number
+): Promise<[T, U]>[] {
+  const values: Promise<[T, U]>[] = new Array(numberValues);
+  const resolvers: Array<(value: [T, U]) => void> = new Array(numberValues);
+
+  for (let i = 0; i < numberValues; i++) {
+    values[i] = new Promise<[T, U]>(resolve => {
+      resolvers[i] = resolve;
+    });
+  }
+
+  let current = 0;
+  function slot(sender: T, args: U) {
+    resolvers[current++]([sender, args]);
+    if (current === numberValues) {
+      cleanup();
+    }
+  }
+  signal.connect(slot);
+
+  function cleanup() {
+    signal.disconnect(slot);
+  }
+  return values;
+}
+
+/**
+ * Convert a signal into a promise for the first emitted value.
+ *
+ * @param signal - The signal we are listening to.
+ *
+ * @returns a Promise that resolves with a `(sender, args)` pair.
+ */
+export function signalToPromise<T, U>(signal: ISignal<T, U>): Promise<[T, U]> {
+  return signalToPromises(signal, 1)[0];
+}
+
+/**
+ * Test to see if a promise is fulfilled.
+ *
+ * @param delay - optional delay in milliseconds before checking
+ * @returns true if the promise is fulfilled (either resolved or rejected), and
+ * false if the promise is still pending.
+ */
+export async function isFulfilled<T>(
+  p: PromiseLike<T>,
+  delay = 0
+): Promise<boolean> {
+  const x = Object.create(null);
+  let race: any;
+  if (delay > 0) {
+    race = sleep(delay, x);
+  } else {
+    race = x;
+  }
+  const result = await Promise.race([p, race]).catch(() => false);
+  return result !== x;
+}
+
+/**
+ * Convert a requestAnimationFrame into a Promise.
+ */
+export function framePromise(): Promise<void> {
+  const done = new PromiseDelegate<void>();
+  requestAnimationFrame(() => {
+    done.resolve(void 0);
+  });
+  return done.promise;
+}
+
+/**
+ * Wait for a dialog to be attached to an element.
+ */
+export async function waitForDialog(
+  host: HTMLElement = document.body,
+  timeout: number = 250
+): Promise<void> {
+  const interval = 25;
+  const limit = Math.floor(timeout / interval);
+  for (let counter = 0; counter < limit; counter++) {
+    if (host.getElementsByClassName('jp-Dialog')[0]) {
+      return;
+    }
+    await sleep(interval);
+  }
+  throw new Error('Dialog not found');
+}
+
+/**
+ * Accept a dialog after it is attached by accepting the default button.
+ */
+export async function acceptDialog(
+  host: HTMLElement = document.body,
+  timeout: number = 250
+): Promise<void> {
+  await waitForDialog(host, timeout);
+
+  const node = host.getElementsByClassName('jp-Dialog')[0];
+
+  if (node) {
+    simulate(node as HTMLElement, 'keydown', { keyCode: 13 });
+  }
+}
+
+/**
+ * Click on the warning button in a dialog after it is attached
+ */
+export async function dangerDialog(
+  host: HTMLElement = document.body,
+  timeout: number = 250
+): Promise<void> {
+  await waitForDialog(host, timeout);
+
+  const node = host.getElementsByClassName('jp-mod-warn')[0];
+
+  if (node) {
+    simulate(node as HTMLElement, 'click', { button: 1 });
+  }
+}
+
+/**
+ * Dismiss a dialog after it is attached.
+ *
+ * #### Notes
+ * This promise will always resolve successfully.
+ */
+export async function dismissDialog(
+  host: HTMLElement = document.body,
+  timeout: number = 250
+): Promise<void> {
+  try {
+    await waitForDialog(host, timeout);
+  } catch (error) {
+    return; // Ignore calls to dismiss the dialog if there is no dialog.
+  }
+
+  const node = host.getElementsByClassName('jp-Dialog')[0];
+
+  if (node) {
+    simulate(node as HTMLElement, 'keydown', { keyCode: 27 });
+  }
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+/* -----------------------------------------------------------------------------
+| Copyright (c) Jupyter Development Team.
+| Distributed under the terms of the Modified BSD License.
+|----------------------------------------------------------------------------*/
+/**
+ * @packageDocumentation
+ * @module testing
+ */
+
+export {
+  testEmission,
+  expectFailure,
+  signalToPromises,
+  signalToPromise,
+  isFulfilled,
+  framePromise,
+  sleep,
+  waitForDialog,
+  acceptDialog,
+  dangerDialog,
+  dismissDialog
+} from './common';
+
+export { JupyterServer } from './start_jupyter_server';

package/src/jest-config.ts

@@ -0,0 +1,56 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+import path from 'path';
+
+const esModules = [
+  '@codemirror',
+  '@jupyter/ydoc',
+  'lib0',
+  'nanoid',
+  'vscode-ws-jsonrpc',
+  'y-protocols',
+  'y-websocket',
+  'yjs'
+].join('|');
+
+module.exports = function (baseDir: string) {
+  return {
+    testEnvironment: 'jsdom',
+    moduleNameMapper: {
+      '\\.(css|less|sass|scss)$': 'identity-obj-proxy',
+      '\\.(gif|ttf|eot)$': '@jupyterlab/testing/lib/jest-file-mock.js'
+    },
+    transform: {
+      '\\.svg$': '@jupyterlab/testing/lib/jest-raw-loader.js',
+      // Extracted from https://github.com/kulshekhar/ts-jest/blob/v29.0.3/presets/index.js
+      '^.+\\.tsx?$': [
+        'ts-jest/legacy',
+        {
+          tsconfig: `./tsconfig.test.json`
+        }
+      ],
+      '^.+\\.jsx?$': 'babel-jest'
+    },
+    testTimeout: 10000,
+    setupFiles: ['@jupyterlab/testing/lib/jest-shim.js'],
+    testPathIgnorePatterns: ['/lib/', '/node_modules/'],
+    moduleFileExtensions: [
+      'ts',
+      'tsx',
+      'js',
+      'jsx',
+      'json',
+      'node',
+      'mjs',
+      'cjs'
+    ],
+    transformIgnorePatterns: [`/node_modules/(?!${esModules}).+`],
+    reporters: ['default', 'jest-junit', 'github-actions'],
+    coverageReporters: ['json', 'lcov', 'text', 'html'],
+    coverageDirectory: path.join(baseDir, 'coverage'),
+    testRegex: '/test/.*.spec.ts[x]?$'
+  };
+};

package/src/jest-file-mock.ts

@@ -0,0 +1,6 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+module.exports = 'test-file-stub';

package/src/jest-raw-loader.ts

@@ -0,0 +1,14 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+// jest-raw-loader compatibility with Jest version 28.
+// See: https://github.com/keplersj/jest-raw-loader/pull/239
+module.exports = {
+  process: (content: string): { code: string } => {
+    return {
+      code: 'module.exports = ' + JSON.stringify(content)
+    };
+  }
+};

package/src/jest-shim.ts

@@ -0,0 +1,137 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+// Shims originally adapted from https://github.com/nteract/nteract/blob/47f8b038ff129543e42c39395129efc433eb4e90/scripts/test-shim.js
+
+/* global globalThis */
+
+globalThis.DragEvent = class DragEvent {} as any;
+
+if (
+  typeof globalThis.TextDecoder === 'undefined' ||
+  typeof globalThis.TextEncoder === 'undefined'
+) {
+  const util = require('util');
+  globalThis.TextDecoder = util.TextDecoder;
+  globalThis.TextEncoder = util.TextEncoder;
+}
+
+const fetchMod = ((window as any).fetch = require('node-fetch'));
+(window as any).Request = fetchMod.Request;
+(window as any).Headers = fetchMod.Headers;
+(window as any).Response = fetchMod.Response;
+
+globalThis.Image = (window as any).Image;
+globalThis.Range = function Range() {
+  /* no-op */
+} as any;
+
+// HACK: Polyfill that allows CodeMirror to render in a JSDOM env.
+const createContextualFragment = (html: string) => {
+  const div = document.createElement('div');
+  div.innerHTML = html;
+  return div.children[0]; // so hokey it's not even funny
+};
+
+globalThis.Range.prototype.createContextualFragment = (html: string) =>
+  createContextualFragment(html) as any;
+
+(window as any).document.createRange = function createRange() {
+  return {
+    setEnd: () => {
+      /* no-op */
+    },
+    setStart: () => {
+      /* no-op */
+    },
+    getBoundingClientRect: () => ({ right: 0 }),
+    getClientRects: (): DOMRect[] => [],
+    createContextualFragment
+  };
+};
+// end CodeMirror HACK
+
+window.focus = () => {
+  /* JSDom throws "Not Implemented" */
+};
+
+(window as any).document.elementFromPoint = (left: number, top: number) =>
+  document.body;
+
+if (!window.hasOwnProperty('getSelection')) {
+  // Minimal getSelection() that supports a fake selection
+  (window as any).getSelection = function getSelection() {
+    return {
+      _selection: '',
+      selectAllChildren: () => {
+        this._selection = 'foo';
+      },
+      toString: () => {
+        const val = this._selection;
+        this._selection = '';
+        return val;
+      }
+    };
+  };
+}
+
+// Used by xterm.js
+(window as any).matchMedia = function (media: string): MediaQueryList {
+  return {
+    matches: false,
+    media,
+    onchange: () => {
+      /* empty */
+    },
+    addEventListener: () => {
+      /* empty */
+    },
+    removeEventListener: () => {
+      /* empty */
+    },
+    dispatchEvent: () => {
+      return true;
+    },
+    addListener: () => {
+      /* empty */
+    },
+    removeListener: () => {
+      /* empty */
+    }
+  };
+};
+
+process.on('unhandledRejection', (error, promise) => {
+  console.error('Unhandled promise rejection somewhere in tests');
+  if (error) {
+    console.error(error);
+    const stack = (error as any).stack;
+    if (stack) {
+      console.error(stack);
+    }
+  }
+  promise.catch(err => console.error('promise rejected', err));
+});
+
+if ((window as any).requestIdleCallback === undefined) {
+  // On Safari, requestIdleCallback is not available, so we use replacement functions for `idleCallbacks`
+  // See: https://developer.mozilla.org/en-US/docs/Web/API/Background_Tasks_API#falling_back_to_settimeout
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  (window as any).requestIdleCallback = function (handler: Function) {
+    let startTime = Date.now();
+    return setTimeout(function () {
+      handler({
+        didTimeout: false,
+        timeRemaining: function () {
+          return Math.max(0, 50.0 - (Date.now() - startTime));
+        }
+      });
+    }, 1);
+  };
+
+  (window as any).cancelIdleCallback = function (id: number) {
+    clearTimeout(id);
+  };
+}

package/src/start_jupyter_server.ts

@@ -0,0 +1,357 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+/* eslint-disable camelcase */
+// Copyright (c) Jupyter Development Team.
+
+import { ChildProcess, spawn } from 'child_process';
+import merge from 'deepmerge';
+import * as fs from 'fs';
+import * as path from 'path';
+
+import { PageConfig, URLExt } from '@jupyterlab/coreutils';
+import { JSONObject, PromiseDelegate, UUID } from '@lumino/coreutils';
+import { sleep } from './common';
+
+/**
+ * A Jupyter Server that runs as a child process.
+ *
+ * ### Notes
+ * There can only be one running server at a time, since
+ * PageConfig is global.  Any classes that use `ServerConnection.ISettings`
+ * such as `ServiceManager` should be instantiated after the server
+ * has fully started so they pick up the right `PageConfig`.
+ *
+ * #### Example
+ * ```typescript
+ * const server = new JupyterServer();
+ *
+ * beforeAll(async () => {
+ *   await server.start();
+ * }, 30000);
+ *
+ * afterAll(async () => {
+ *  await server.shutdown();
+ * });
+ * ```
+ *
+ */
+export class JupyterServer {
+  /**
+   * Start the server.
+   *
+   * @returns A promise that resolves with the url of the server
+   *
+   * @throws Error if another server is still running.
+   */
+  async start(options: Partial<JupyterServer.IOptions> = {}): Promise<string> {
+    if (Private.child !== null) {
+      throw Error('Previous server was not disposed');
+    }
+    const startDelegate = new PromiseDelegate<string>();
+
+    const env = {
+      JUPYTER_CONFIG_DIR: Private.handleConfig(options),
+      JUPYTER_DATA_DIR: Private.handleData(options),
+      JUPYTER_RUNTIME_DIR: Private.mktempDir('jupyter_runtime'),
+      IPYTHONDIR: Private.mktempDir('ipython'),
+      PATH: process.env.PATH
+    };
+
+    // Create the child process for the server.
+    const child = (Private.child = spawn('jupyter-lab', { env }));
+
+    let started = false;
+
+    // Handle server output.
+    const handleOutput = (output: string) => {
+      console.debug(output);
+
+      if (started) {
+        return;
+      }
+      const baseUrl = Private.handleStartup(output);
+      if (baseUrl) {
+        console.debug('Jupyter Server started');
+        started = true;
+        void Private.connect(baseUrl, startDelegate);
+      }
+    };
+
+    child.stdout.on('data', data => {
+      handleOutput(String(data));
+    });
+
+    child.stderr.on('data', data => {
+      handleOutput(String(data));
+    });
+
+    const url = await startDelegate.promise;
+    return url;
+  }
+
+  /**
+   * Shut down the server, waiting for it to exit gracefully.
+   */
+  async shutdown(): Promise<void> {
+    if (!Private.child) {
+      return Promise.resolve(void 0);
+    }
+    const stopDelegate = new PromiseDelegate<void>();
+    const child = Private.child;
+    child.on('exit', code => {
+      Private.child = null;
+      if (code !== null && code !== 0) {
+        stopDelegate.reject('child process exited with code ' + String(code));
+      } else {
+        stopDelegate.resolve(void 0);
+      }
+    });
+
+    child.kill();
+    window.setTimeout(() => {
+      if (Private.child) {
+        Private.child.kill(9);
+      }
+    }, 3000);
+
+    return stopDelegate.promise;
+  }
+}
+
+/**
+ * A namespace for JupyterServer static values.
+ */
+export namespace JupyterServer {
+  /**
+   * Options used to create a new JupyterServer instance.
+   */
+  export interface IOptions {
+    /**
+     * Additional Page Config values.
+     */
+    pageConfig: { [name: string]: string };
+    /**
+     * Additional traitlet config data.
+     */
+    configData: JSONObject;
+    /**
+     * Map of additional kernelspec names to kernel.json dictionaries
+     */
+    additionalKernelSpecs: JSONObject;
+  }
+}
+
+/**
+ * A namespace for module private data.
+ */
+namespace Private {
+  export let child: ChildProcess | null = null;
+
+  /**
+   * Make a temporary directory.
+   *
+   * @param suffix the last portion of the dir naem.
+   */
+  export function mktempDir(suffix: string): string {
+    const pathPrefix = '/tmp/jupyterServer';
+    if (!fs.existsSync(pathPrefix)) {
+      fs.mkdirSync(pathPrefix);
+    }
+    return fs.mkdtempSync(`${pathPrefix}/${suffix}`);
+  }
+
+  /**
+   * Install a spec in the data directory.
+   */
+  // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
+  export function installSpec(dataDir: string, name: string, spec: any): void {
+    const specDir = path.join(dataDir, 'kernels', name);
+    fs.mkdirSync(specDir, { recursive: true });
+    fs.writeFileSync(path.join(specDir, 'kernel.json'), JSON.stringify(spec));
+    PageConfig.setOption(`__kernelSpec_${name}`, JSON.stringify(spec));
+  }
+
+  /**
+   * Create and populate a notebook directory.
+   */
+  function createNotebookDir(): string {
+    const nbDir = mktempDir('notebook');
+    fs.mkdirSync(path.join(nbDir, 'src'));
+    fs.writeFileSync(path.join(nbDir, 'src', 'temp.txt'), 'hello');
+
+    const roFilepath = path.join(nbDir, 'src', 'readonly-temp.txt');
+    fs.writeFileSync(roFilepath, 'hello from a ready only file', {
+      mode: 0o444
+    });
+    return nbDir;
+  }
+
+  /**
+   * Create a temporary directory for schemas.
+   */
+  function createAppDir(): string {
+    const appDir = mktempDir('app');
+
+    // Add a fake static/index.html for `ensure_app_check()`
+    fs.mkdirSync(path.join(appDir, 'static'));
+    fs.writeFileSync(path.join(appDir, 'static', 'index.html'), 'foo');
+
+    // Add the apputils schema.
+    const schemaDir = path.join(appDir, 'schemas');
+    fs.mkdirSync(schemaDir, { recursive: true });
+    const extensionDir = path.join(
+      schemaDir,
+      '@jupyterlab',
+      'apputils-extension'
+    );
+    fs.mkdirSync(extensionDir, { recursive: true });
+
+    // Get schema content.
+    const schema = {
+      title: 'Theme',
+      description: 'Theme manager settings.',
+      properties: {
+        theme: {
+          type: 'string',
+          title: 'Selected Theme',
+          default: 'JupyterLab Light'
+        }
+      },
+      type: 'object'
+    };
+    fs.writeFileSync(
+      path.join(extensionDir, 'themes.json'),
+      JSON.stringify(schema)
+    );
+    return appDir;
+  }
+
+  /**
+   * Handle configuration.
+   */
+  export function handleConfig(
+    options: Partial<JupyterServer.IOptions>
+  ): string {
+    // Set up configuration.
+    const token = UUID.uuid4();
+    PageConfig.setOption('token', token);
+    PageConfig.setOption('terminalsAvailable', 'true');
+
+    if (options.pageConfig) {
+      Object.keys(options.pageConfig).forEach(key => {
+        PageConfig.setOption(key, options.pageConfig![key]);
+      });
+    }
+
+    const configDir = mktempDir('config');
+    const configPath = path.join(configDir, 'jupyter_server_config.json');
+    const root_dir = createNotebookDir();
+
+    const app_dir = createAppDir();
+    const user_settings_dir = mktempDir('settings');
+    const workspaces_dir = mktempDir('workspaces');
+
+    const configData = merge(
+      {
+        LabApp: {
+          user_settings_dir,
+          workspaces_dir,
+          app_dir,
+          open_browser: false,
+          log_level: 'DEBUG'
+        },
+        ServerApp: {
+          token,
+          root_dir,
+          log_level: 'DEBUG'
+        },
+        MultiKernelManager: {
+          default_kernel_name: 'echo'
+        },
+        KernelManager: {
+          shutdown_wait_time: 1.0
+        }
+      },
+      options.configData || {}
+    );
+    PageConfig.setOption('__configData', JSON.stringify(configData));
+    fs.writeFileSync(configPath, JSON.stringify(configData));
+    return configDir;
+  }
+
+  /**
+   * Handle data.
+   */
+  export function handleData(options: Partial<JupyterServer.IOptions>): string {
+    const dataDir = mktempDir('data');
+
+    // Install custom specs.
+    installSpec(dataDir, 'echo', {
+      argv: [
+        'python',
+        '-m',
+        'jupyterlab.tests.echo_kernel',
+        '-f',
+        '{connection_file}'
+      ],
+      display_name: 'Echo Kernel',
+      language: 'echo'
+    });
+
+    installSpec(dataDir, 'ipython', {
+      argv: ['python', '-m', 'ipykernel_launcher', '-f', '{connection_file}'],
+      display_name: 'Python 3',
+      language: 'python'
+    });
+
+    if (options.additionalKernelSpecs) {
+      Object.keys(options.additionalKernelSpecs).forEach(key => {
+        installSpec(dataDir, key, options.additionalKernelSpecs![key]);
+      });
+    }
+    return dataDir;
+  }
+
+  /**
+   * Handle process startup.
+   *
+   * @param output the process output
+   *
+   * @returns The baseUrl of the server or `null`.
+   */
+  export function handleStartup(output: string): string | null {
+    let baseUrl: string | null = null;
+    output.split('\n').forEach(line => {
+      const baseUrlMatch = line.match(/(http:\/\/localhost:\d+\/[^?]*)/);
+      if (baseUrlMatch) {
+        baseUrl = baseUrlMatch[1].replace('/lab', '');
+        PageConfig.setOption('baseUrl', baseUrl);
+      }
+    });
+    return baseUrl;
+  }
+
+  /**
+   * Connect to the Jupyter server.
+   */
+  export async function connect(
+    baseUrl: string,
+    startDelegate: PromiseDelegate<string>
+  ): Promise<void> {
+    // eslint-disable-next-line
+    while (true) {
+      try {
+        await fetch(URLExt.join(baseUrl, 'api'));
+        startDelegate.resolve(baseUrl);
+        return;
+      } catch (e) {
+        // spin until we can connect to the server.
+        console.warn(e);
+        await sleep(1000);
+      }
+    }
+  }
+}