@jupyterlab/galata 5.0.0-alpha.2 → 5.0.0-alpha.21

package/src/extension.ts

@@ -0,0 +1,281 @@
+// Copyright (c) Jupyter Development Team.
+// Copyright (c) Bloomberg Finance LP.
+// Distributed under the terms of the Modified BSD License.
+
+// This export the types (and only the types) from extension/token.ts
+// Required for typedoc to be happy otherwise we could have used `from '@jupyterlab/extension/lib/token';`
+
+import type { JupyterFrontEnd } from '@jupyterlab/application';
+import type { IRouter } from '@jupyterlab/application';
+import type {
+  Dialog,
+  Notification,
+  NotificationManager,
+  WidgetTracker
+} from '@jupyterlab/apputils';
+import type { IDocumentManager } from '@jupyterlab/docmanager';
+import type { ISettingRegistry } from '@jupyterlab/settingregistry';
+
+declare global {
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  interface Window {
+    /**
+     * Access Jupyter Application object
+     */
+    jupyterapp: JupyterFrontEnd;
+    /**
+     * Access to Galata In-Page helpers
+     *
+     * Those helpers are injected through a JupyterLab extension
+     */
+    galata: IGalataInpage;
+    /**
+     * Access to Galata In-Page helpers
+     *
+     * @deprecated since v4
+     * Those helpers are injected through a JupyterLab extension
+     */
+    galataip: IGalataInpage;
+  }
+}
+
+/**
+ * Static objects exposed.
+ */
+export interface IGalataHelpers {
+  /**
+   * JupyterLab dialogs tracker.
+   */
+  readonly dialogs: WidgetTracker<Dialog<any>>;
+  /**
+   * JupyterLab notifications manager.
+   */
+  readonly notifications: NotificationManager;
+}
+
+/**
+ * Cell execution callbacks interface
+ */
+export interface INotebookRunCallback {
+  /**
+   * Callback before scrolling to the cell
+   */
+  onBeforeScroll?: () => Promise<void>;
+  /**
+   * Callback after scrolling to the cell
+   */
+  onAfterScroll?: () => Promise<void>;
+  /**
+   * Callback after cell execution
+   */
+  onAfterCellRun?: (cellIndex: number) => Promise<void>;
+}
+
+/**
+ * waitForSelector options
+ */
+export interface IWaitForSelectorOptions {
+  /**
+   * Test for the element to be hidden.
+   */
+  hidden?: boolean;
+}
+
+export interface IPluginNameToInterfaceMap {
+  '@jupyterlab/galata-extension:helpers': IGalataHelpers;
+  '@jupyterlab/application-extension:router': IRouter;
+  '@jupyterlab/docmanager-extension:manager': IDocumentManager;
+  '@jupyterlab/apputils-extension:settings': ISettingRegistry;
+}
+
+/**
+ * Galata In-Page interface
+ */
+export interface IGalataInpage {
+  /**
+   * Delete all cells of the active notebook
+   */
+  deleteNotebookCells(): Promise<void>;
+
+  /**
+   * Get the index of a toolbar item
+   *
+   * @param itemName Item name
+   * @returns Index
+   */
+  getNotebookToolbarItemIndex(itemName: string): number;
+
+  /**
+   * Get an application plugin
+   *
+   * @param pluginId Plugin ID
+   * @returns Application plugin
+   */
+  getPlugin<K extends keyof IPluginNameToInterfaceMap>(
+    pluginId: K
+  ): Promise<IPluginNameToInterfaceMap[K] | undefined>;
+
+  /**
+   * Get the Jupyter notifications.
+   *
+   * @returns Jupyter Notifications
+   */
+  getNotifications(): Promise<Notification.INotification[]>;
+
+  /**
+   * Test if one or all cells have an execution number.
+   *
+   * @param cellIndex Cell index
+   * @returns Whether the cell was executed or not
+   *
+   * ### Notes
+   * It checks that no cells have a `null` execution count.
+   */
+  haveBeenExecuted(cellIndex?: number): boolean;
+
+  /**
+   * Test if a cell is selected in the active notebook
+   *
+   * @param cellIndex Cell index
+   * @returns Whether the cell is selected or not
+   */
+  isNotebookCellSelected(cellIndex: number): boolean;
+
+  /**
+   * Test if a element is visible or not
+   *
+   * @param el Element
+   * @returns Test result
+   */
+  isElementVisible(el: HTMLElement): boolean;
+
+  /**
+   * Disconnect a listener to new Jupyter dialog events.
+   *
+   * @param event Event type
+   * @param listener Event listener
+   */
+  off(event: 'dialog', listener: (dialog: Dialog<any> | null) => void): void;
+  /**
+   * Disconnect a listener to new or updated Jupyter notification events.
+   *
+   * @param event Event type
+   * @param listener Event listener
+   */
+  off(
+    event: 'notification',
+    listener: (notification: Notification.INotification) => void
+  ): void;
+
+  /**
+   * Connect a listener to new Jupyter dialog events.
+   *
+   * @param event Event type
+   * @param listener Event listener
+   */
+  on(event: 'dialog', listener: (dialog: Dialog<any> | null) => void): void;
+
+  /**
+   * Connect a listener to new or updated Jupyter notification events.
+   *
+   * @param event Event type
+   * @param listener Event listener
+   */
+  on(
+    event: 'notification',
+    listener: (notification: Notification.INotification) => void
+  ): void;
+
+  /**
+   * Connect a listener to the next new Jupyter dialog event.
+   *
+   * @param event Event type
+   * @param listener Event listener
+   */
+  once(event: 'dialog', listener: (dialog: Dialog<any> | null) => void): void;
+
+  /**
+   * Connect a listener to the next new or updated Jupyter notification event.
+   *
+   * @param event Event type
+   * @param listener Event listener
+   */
+  once(
+    event: 'notification',
+    listener: (notification: Notification.INotification) => void
+  ): void;
+
+  /**
+   * Save the active notebook
+   */
+  saveActiveNotebook(): Promise<void>;
+
+  /**
+   * Set the application theme
+   *
+   * @param themeName Theme name
+   */
+  setTheme(themeName: string): Promise<void>;
+
+  /**
+   * Reset execution count of one or all cells.
+   *
+   * @param cellIndex Cell index
+   */
+  resetExecutionCount(cellIndex?: number): void;
+
+  /**
+   * Run the active notebook cell by cell
+   * and execute the callback after each cell execution
+   *
+   * @param callback Callback
+   */
+  runActiveNotebookCellByCell(callback?: INotebookRunCallback): Promise<void>;
+
+  /**
+   * Wait for the route to be on path and close all documents
+   *
+   * @param path Path to monitor
+   */
+  waitForLaunch(path?: string): Promise<void>;
+
+  /**
+   * Wait for an element to be found from a CSS selector
+   *
+   * @param selector CSS selector
+   * @param node Element
+   * @param options Options
+   * @returns Selected element
+   */
+  waitForSelector(
+    selector: string,
+    node?: Element,
+    options?: IWaitForSelectorOptions
+  ): Promise<Node | null>;
+
+  /**
+   * Waits for the given `timeout` in milliseconds.
+   *
+   * @param timeout A timeout to wait for
+   */
+  waitForTimeout(duration: number): Promise<void>;
+
+  /**
+   * Wait for an element to be found from a XPath
+   *
+   * @param selector CSS selector
+   * @param node Element
+   * @param options Options
+   * @returns Selected element
+   */
+  waitForXPath(
+    selector: string,
+    node?: Element,
+    options?: IWaitForSelectorOptions
+  ): Promise<Node | null>;
+
+  /**
+   * Application object
+   */
+  readonly app: JupyterFrontEnd;
+}

package/src/fixtures.ts

@@ -0,0 +1,387 @@
+/* eslint-disable @typescript-eslint/ban-ts-comment */
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import type { Session, TerminalAPI, User } from '@jupyterlab/services';
+import {
+  test as base,
+  Page,
+  PlaywrightTestArgs,
+  PlaywrightTestOptions,
+  PlaywrightWorkerArgs,
+  PlaywrightWorkerOptions,
+  TestType
+} from '@playwright/test';
+import * as path from 'path';
+import { ContentsHelper } from './contents';
+import { galata } from './galata';
+import { IJupyterLabPage, IJupyterLabPageFixture } from './jupyterlabpage';
+
+/**
+ * Galata test arguments
+ */
+export interface IGalataTestArgs extends PlaywrightTestArgs {
+  /**
+   * JupyterLab test page.
+   *
+   * It brings the following feature on top of Playwright Page object:
+   * - Goto to JupyterLab URL and wait for the application to be ready
+   * - Helpers for JupyterLab
+   * - Settings mock-up
+   * - State mock-up
+   * - Track sessions and terminals opened during a test to close them at the end
+   *
+   * Note: If autoGoto is true, the filebrowser will be set inside tmpPath.
+   * Nothing is preventing you to navigate to some other folders.
+   * So you must avoid creating files outside that directory to avoid
+   * coupling effects between tests.
+   *
+   */
+  page: IJupyterLabPageFixture;
+}
+
+/**
+ * Galata test configuration
+ */
+export type GalataOptions = {
+  /**
+   * Application URL path fragment.
+   *
+   * Default: /lab
+   */
+  appPath: string;
+  /**
+   * Whether to go to JupyterLab page within the fixture or not.
+   *
+   * Default: true
+   */
+  autoGoto: boolean;
+  /**
+   * Mock JupyterLab config in-memory or not.
+   *
+   * Possible values are:
+   * - true (default): JupyterLab config will be mocked on a per test basis
+   * - false: JupyterLab config won't be mocked (Be careful it will write config in local files)
+   * - Record<string, JSONObject>: Initial JupyterLab data config - Mapping (config section, value).
+   *
+   * By default the config is stored in-memory.
+   */
+  mockConfig: boolean | Record<string, unknown>;
+  /**
+   * Mock JupyterLab state in-memory or not.
+   *
+   * Possible values are:
+   * - true (default): JupyterLab state will be mocked on a per test basis
+   * - false: JupyterLab state won't be mocked (Be careful it will write state in local files)
+   * - Record<string, unknown>: Initial JupyterLab data state - Mapping (state key, value).
+   *
+   * By default the state is stored in-memory.
+   */
+  mockState: boolean | Record<string, unknown>;
+  /**
+   * Mock JupyterLab settings in-memory or not.
+   *
+   * Possible values are:
+   * - true: JupyterLab settings will be mocked on a per test basis
+   * - false: JupyterLab settings won't be mocked (Be careful it will read & write settings local files)
+   * - Record<string, unknown>: Mapping {pluginId: settings} that will be default user settings
+   *
+   * The default value is `galata.DEFAULT_SETTINGS`
+   *
+   * By default the settings are stored in-memory. However the
+   * they are still initialized with the hard drive values.
+   */
+  mockSettings: boolean | Record<string, unknown>;
+  /**
+   * Mock JupyterLab user in-memory or not.
+   *
+   * Possible values are:
+   * - true (default): JupyterLab user will be mocked on a per test basis
+   * - false: JupyterLab user won't be mocked (It will be a random user so snapshots won't match)
+   * - Record<string, unknown>: Initial JupyterLab user - Mapping (user attribute, value).
+   *
+   * By default the user is stored in-memory.
+   */
+  mockUser: boolean | Partial<User.IUser>;
+  /**
+   * Galata can keep the uploaded and created files in ``tmpPath`` on
+   * the server root for debugging purpose. By default the files are
+   * always deleted
+   *
+   * - 'off' - ``tmpPath`` is deleted after each tests
+   * - 'on' - ``tmpPath`` is never deleted
+   * - 'only-on-failure' - ``tmpPath`` is deleted except if a test failed or timed out.
+   */
+  serverFiles: 'on' | 'off' | 'only-on-failure';
+  /**
+   * Sessions created during the test.
+   *
+   * Possible values are:
+   * - null: The sessions API won't be mocked
+   * - Map<string, Session.IModel>: The sessions created during a test.
+   *
+   * By default the sessions created during a test will be tracked and disposed at the end.
+   */
+  sessions: Map<string, Session.IModel> | null;
+  /**
+   * Terminals created during the test.
+   *
+   * Possible values are:
+   * - null: The Terminals API won't be mocked
+   * - Map<string, TerminalsAPI.IModel>: The Terminals created during a test.
+   *
+   * By default the Terminals created during a test will be tracked and disposed at the end.
+   */
+  terminals: Map<string, TerminalAPI.IModel> | null;
+  /**
+   * Unique test temporary path created on the server.
+   *
+   * Note: if you override this string, you will need to take care of creating the
+   * folder and cleaning it.
+   */
+  tmpPath: string;
+  /**
+   * Wait for the application page to be ready.
+   *
+   * @param page Playwright Page model
+   * @param helpers JupyterLab helpers
+   */
+  waitForApplication: (page: Page, helpers: IJupyterLabPage) => Promise<void>;
+};
+
+/**
+ * JupyterLab customized test.
+ */
+// @ts-ignore
+export const test: TestType<
+  IGalataTestArgs & GalataOptions & PlaywrightTestOptions,
+  PlaywrightWorkerArgs & PlaywrightWorkerOptions
+> = base.extend<GalataOptions>({
+  /**
+   * `baseURL` used for all pages in the test. Takes priority over `contextOptions`.
+   * @see BrowserContextOptions
+   *
+   * It can also be set with `TARGET_URL` environment variable and default to `http://localhost:8888`.
+   */
+  baseURL: async ({ baseURL }, use) => {
+    await use(baseURL ?? process.env.TARGET_URL ?? 'http://localhost:8888');
+  },
+  /**
+   * Application URL path fragment.
+   *
+   * Default: /lab
+   */
+  appPath: ['/lab', { option: true }],
+  /**
+   * Whether to go to JupyterLab page within the fixture or not.
+   *
+   * Default: true.
+   *
+   * Note: Setting it to false allows to register new route mock-ups for example.
+   */
+  autoGoto: [true, { option: true }],
+  /**
+   * Mock JupyterLab config in-memory or not.
+   *
+   * Possible values are:
+   * - true (default): JupyterLab config will be mocked on a per test basis
+   * - false: JupyterLab config won't be mocked (Be careful it will write config in local files)
+   * - Record<string, JSONObject>: Initial JupyterLab data config - Mapping (config section, value).
+   *
+   * By default the config is stored in-memory.
+   */
+  mockConfig: [true, { option: true }],
+  /**
+   * Mock JupyterLab state in-memory or not.
+   *
+   * Possible values are:
+   * - true (default): JupyterLab state will be mocked on a per test basis
+   * - false: JupyterLab state won't be mocked (Be careful it will write state in local files)
+   * - Record<string, unknown>: Initial JupyterLab data state - Mapping (state key, value).
+   *
+   * By default the state is stored in-memory
+   */
+  mockState: [true, { option: true }],
+  /**
+   * Mock JupyterLab settings in-memory or not.
+   *
+   * Possible values are:
+   * - true: JupyterLab settings will be mocked on a per test basis
+   * - false: JupyterLab settings won't be mocked (Be careful it may write settings local files)
+   * - Record<string, unknown>: Mapping {pluginId: settings} that will be default user settings
+   *
+   * The default value is `galata.DEFAULT_SETTINGS`
+   *
+   * By default the settings are stored in-memory. However the
+   * they are still initialized with the hard drive values.
+   */
+  mockSettings: [galata.DEFAULT_SETTINGS, { option: true }],
+  /**
+   * Mock JupyterLab user in-memory or not.
+   *
+   * Possible values are:
+   * - true (default): JupyterLab user will be mocked on a per test basis
+   * - false: JupyterLab user won't be mocked (It will be a random user so snapshots won't match)
+   * - Record<string, unknown>: Initial JupyterLab user - Mapping (user attribute, value).
+   *
+   * By default the user is stored in-memory.
+   */
+  mockUser: [true, { option: true }],
+  /**
+   * Galata can keep the uploaded and created files in ``tmpPath`` on
+   * the server root for debugging purpose. By default the files are
+   * always deleted.
+   *
+   * - 'off' - ``tmpPath`` is deleted after each tests
+   * - 'on' - ``tmpPath`` is never deleted
+   * - 'only-on-failure' - ``tmpPath`` is deleted except if a test failed or timed out.
+   */
+  serverFiles: ['off', { option: true }],
+  /**
+   * Sessions created during the test.
+   *
+   * Possible values are:
+   * - null: The sessions API won't be mocked
+   * - Map<string, Session.IModel>: The sessions created during a test.
+   *
+   * By default the sessions created during a test will be tracked and disposed at the end.
+   */
+  sessions: async ({ request }, use) => {
+    const sessions = new Map<string, Session.IModel>();
+
+    await use(sessions);
+
+    if (sessions.size > 0) {
+      await galata.Mock.clearRunners(request, [...sessions.keys()], 'sessions');
+    }
+  },
+  /**
+   * Terminals created during the test.
+   *
+   * Possible values are:
+   * - null: The Terminals API won't be mocked
+   * - Map<string, TerminalAPI.IModel>: The Terminals created during a test.
+   *
+   * By default the Terminals created during a test will be tracked and disposed at the end.
+   */
+  terminals: async ({ request }, use) => {
+    const terminals = new Map<string, TerminalAPI.IModel>();
+
+    await use(terminals);
+
+    if (terminals.size > 0) {
+      await galata.Mock.clearRunners(
+        request,
+        [...terminals.keys()],
+        'terminals'
+      );
+    }
+  },
+  /**
+   * Unique test temporary path created on the server.
+   *
+   * Note: if you override this string, you will need to take care of creating the
+   * folder and cleaning it.
+   */
+  tmpPath: async ({ request, serverFiles }, use, testInfo) => {
+    // Remove appended retry part for reproducibility
+    const testFolder = path
+      .basename(testInfo.outputDir)
+      .replace(/-retry\d+$/i, '');
+
+    const contents = new ContentsHelper(request);
+
+    if (await contents.directoryExists(testFolder)) {
+      await contents.deleteDirectory(testFolder);
+    }
+
+    // Create the test folder on the server
+    await contents.createDirectory(testFolder);
+
+    await use(testFolder);
+
+    // Delete the test folder on the server
+    // If serverFiles is 'on' or 'only-on-failure', keep the server files for the test
+    if (
+      serverFiles === 'off' ||
+      (serverFiles === 'only-on-failure' &&
+        (testInfo.status === 'passed' || testInfo.status === 'skipped'))
+    ) {
+      await contents.deleteDirectory(testFolder);
+    }
+  },
+  /**
+   * Wait for the application page to be ready
+   *
+   * @param page Playwright Page model
+   * @param helpers JupyterLab helpers
+   */
+  waitForApplication: async ({ baseURL }, use) => {
+    const waitIsReady = async (
+      page: Page,
+      helpers: IJupyterLabPage
+    ): Promise<void> => {
+      await page.waitForSelector('#jupyterlab-splash', {
+        state: 'detached'
+      });
+      await helpers.waitForCondition(() => {
+        return helpers.activity.isTabActive('Launcher');
+      });
+      // Oddly current tab is not always set to active
+      if (!(await helpers.isInSimpleMode())) {
+        await helpers.activity.activateTab('Launcher');
+      }
+    };
+    await use(waitIsReady);
+  },
+  /**
+   * JupyterLab test page.
+   *
+   * It brings the following feature on top of Playwright Page object:
+   * - Goto to JupyterLab URL and wait for the application to be ready (autoGoto == true)
+   * - Helpers for JupyterLab
+   * - Settings mock-up
+   * - State mock-up
+   * - Track sessions and terminals opened during a test to close them at the end
+   *
+   * Note: If autoGoto is true, the filebrowser will be set inside tmpPath.
+   * Nothing is preventing you to navigate to some other folders.
+   * So you must avoid creating files outside that directory to avoid
+   * coupling effects between tests.
+   */
+  // @ts-ignore
+  page: async (
+    {
+      appPath,
+      autoGoto,
+      baseURL,
+      mockConfig,
+      mockSettings,
+      mockState,
+      mockUser,
+      page,
+      sessions,
+      terminals,
+      tmpPath,
+      waitForApplication
+    },
+    use
+  ) => {
+    await use(
+      await galata.initTestPage(
+        appPath,
+        autoGoto,
+        baseURL!,
+        mockConfig,
+        mockSettings,
+        mockState,
+        mockUser,
+        page,
+        sessions,
+        terminals,
+        tmpPath,
+        waitForApplication
+      )
+    );
+  }
+});