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

package/lib/extension/tokens.d.ts

@@ -0,0 +1,232 @@
+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';
+import { Token } from '@lumino/coreutils';
+declare global {
+    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;
+    }
+}
+/**
+ * Galata in-page extension helpers.
+ */
+export declare const PLUGIN_ID_GALATA_HELPERS = "@jupyterlab/galata-extension:helpers";
+/**
+ * Static objects exposed.
+ */
+export interface IGalataHelpers {
+    /**
+     * JupyterLab dialogs tracker.
+     */
+    readonly dialogs: WidgetTracker<Dialog<any>>;
+    /**
+     * JupyterLab notifications manager.
+     */
+    readonly notifications: NotificationManager;
+}
+/**
+ * Test token exposing some static JupyterLab objects.
+ */
+export declare const IGalataHelpers: Token<IGalataHelpers>;
+/**
+ * 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 {
+    [PLUGIN_ID_GALATA_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/lib/extension/tokens.js

@@ -0,0 +1,13 @@
+// Copyright (c) Jupyter Development Team.
+// Copyright (c) Bloomberg Finance LP.
+// Distributed under the terms of the Modified BSD License.
+import { Token } from '@lumino/coreutils';
+/**
+ * Galata in-page extension helpers.
+ */
+export const PLUGIN_ID_GALATA_HELPERS = '@jupyterlab/galata-extension:helpers';
+/**
+ * Test token exposing some static JupyterLab objects.
+ */
+export const IGalataHelpers = new Token('@jupyterlab/galata-extension:IGalataHelpers');
+//# sourceMappingURL=tokens.js.map

package/lib/extension/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../../extension/src/tokens.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAC1C,sCAAsC;AACtC,2DAA2D;AAY3D,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAyB1C;;GAEG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,sCAAsC,CAAC;AAgB/E;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,KAAK,CACrC,6CAA6C,CAC9C,CAAC"}

package/lib/extension.d.ts

@@ -0,0 +1,223 @@
+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 {
+    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/lib/{global.js → extension.js}

@@ -1,7 +1,6 @@
 "use strict";
-/* eslint-disable @typescript-eslint/naming-convention */
 // Copyright (c) Jupyter Development Team.
 // Copyright (c) Bloomberg Finance LP.
 // Distributed under the terms of the Modified BSD License.
 Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=global.js.map
+//# sourceMappingURL=extension.js.map

package/lib/extension.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension.js","sourceRoot":"","sources":["../src/extension.ts"],"names":[],"mappings":";AAAA,0CAA0C;AAC1C,sCAAsC;AACtC,2DAA2D"}

package/lib/fixtures.d.ts

@@ -1,4 +1,4 @@
-import { Session, TerminalAPI } from '@jupyterlab/services';
+import type { Session, TerminalAPI, User } from '@jupyterlab/services';
 import { Page, PlaywrightTestArgs, PlaywrightTestOptions, PlaywrightWorkerArgs, PlaywrightWorkerOptions, TestType } from '@playwright/test';
 import { IJupyterLabPage, IJupyterLabPageFixture } from './jupyterlabpage';
 /**
@@ -26,7 +26,7 @@ export interface IGalataTestArgs extends PlaywrightTestArgs {
 /**
  * Galata test configuration
  */
-export declare type GalataOptions = {
+export type GalataOptions = {
     /**
      * Application URL path fragment.
      *
@@ -40,15 +40,16 @@ export declare type GalataOptions = {
      */
     autoGoto: boolean;
     /**
-     * Galata can keep the uploaded and created files in ``tmpPath`` on
-     * the server root for debugging purpose. By default the files are
-     * always deleted
+     * Mock JupyterLab config in-memory or not.
      *
-     * - '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.
+     * 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.
      */
-    serverFiles: 'on' | 'off' | 'only-on-failure';
+    mockConfig: boolean | Record<string, unknown>;
     /**
      * Mock JupyterLab state in-memory or not.
      *
@@ -74,6 +75,27 @@ export declare type GalataOptions = {
      * 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.
      *
@@ -102,7 +124,7 @@ export declare type GalataOptions = {
      */
     tmpPath: string;
     /**
-     * Wait for the application page to be ready
+     * Wait for the application page to be ready.
      *
      * @param page Playwright Page model
      * @param helpers JupyterLab helpers