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

package/src/helpers/performance.ts

@@ -0,0 +1,57 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import { Page } from '@playwright/test';
+import { UUID } from '@lumino/coreutils';
+
+/**
+ * Performance helper
+ */
+export class PerformanceHelper {
+  constructor(readonly page: Page) {}
+
+  /**
+   * Clear all measures and place a mark
+   *
+   * @param name Mark
+   */
+  startTimer(name: string = 'start'): Promise<void> {
+    return this.page.evaluate(`{
+      performance.clearMeasures();
+      performance.mark('${name}');
+    }`);
+  }
+
+  /**
+   * Get the duration since the mark has been created
+   *
+   * @param startMark Mark
+   * @param name Measure
+   * @returns Measure value
+   */
+  async endTimer(
+    startMark: string = 'start',
+    name: string = 'duration'
+  ): Promise<number> {
+    await this.page.evaluate(`performance.measure('${name}', '${startMark}')`);
+    const time: number = await this.page.evaluate(
+      `performance.getEntriesByName('${name}')[0].duration`
+    );
+    return time;
+  }
+
+  /**
+   * Measure the time to execute a function using web browser performance API.
+   *
+   * @param fn Function to measure
+   * @returns The duration to execute the function
+   */
+  async measure(fn: () => Promise<void>): Promise<number> {
+    const mark = UUID.uuid4();
+    await this.startTimer(mark);
+
+    await fn();
+
+    return this.endTimer(mark);
+  }
+}

package/src/helpers/sidebar.ts

@@ -0,0 +1,289 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import type { ISettingRegistry } from '@jupyterlab/settingregistry';
+import { ElementHandle, Page } from '@playwright/test';
+import type { IPluginNameToInterfaceMap } from '../extension';
+import { galata } from '../galata';
+import * as Utils from '../utils';
+import { MenuHelper } from './menu';
+
+/**
+ * Sidebar helpers
+ */
+export class SidebarHelper {
+  constructor(readonly page: Page, readonly menu: MenuHelper) {}
+
+  /**
+   * Whether a sidebar is opened or not
+   *
+   * @param side Sidebar side
+   * @returns Opened status
+   */
+  isOpen = async (side: galata.SidebarPosition = 'left'): Promise<boolean> => {
+    return (await this.getContentPanel(side)) !== null;
+  };
+
+  /**
+   * Whether a given tab is opened or not
+   *
+   * @param id Tab id
+   * @returns Tab opened status
+   */
+  async isTabOpen(id: galata.SidebarTabId): Promise<boolean> {
+    const tabButton = await this.page.$(
+      `${this.buildTabSelector(id)}.lm-mod-current`
+    );
+    return tabButton !== null;
+  }
+
+  /**
+   * Get the position of a given tab
+   *
+   * @param id Tab id
+   * @returns Tab position
+   */
+  getTabPosition = async (
+    id: galata.SidebarTabId
+  ): Promise<galata.SidebarPosition | null> => {
+    return await this.page.evaluate(
+      async ({ tabSelector }) => {
+        const tabButton = document.querySelector(tabSelector);
+        if (!tabButton) {
+          return null;
+        }
+
+        const sideBar = tabButton.closest('.jp-SideBar');
+        if (!sideBar) {
+          return null;
+        }
+
+        return sideBar.classList.contains('jp-mod-right') ? 'right' : 'left';
+      },
+      { tabSelector: this.buildTabSelector(id) }
+    );
+  };
+
+  /**
+   * Move a given tab to left side
+   *
+   * @param id Tab id
+   */
+  async moveTabToLeft(id: galata.SidebarTabId): Promise<void> {
+    await this.setTabPosition(id, 'left');
+  }
+
+  /**
+   * Move a given tab to the right side
+   *
+   * @param id Tab id
+   */
+  async moveTabToRight(id: galata.SidebarTabId): Promise<void> {
+    await this.setTabPosition(id, 'right');
+  }
+
+  /**
+   * Set the position of a given tab
+   *
+   * @param id Tab id
+   * @param side Sidebar side
+   */
+  async setTabPosition(
+    id: galata.SidebarTabId,
+    side: galata.SidebarPosition
+  ): Promise<void> {
+    const position = await this.getTabPosition(id);
+
+    if (position === side) {
+      return;
+    }
+
+    await this.toggleTabPosition(id);
+
+    await Utils.waitForCondition(async () => {
+      return (await this.getTabPosition(id)) === side;
+    });
+  }
+
+  /**
+   * Toggle a given tab position
+   *
+   * @param id Tab id
+   */
+  async toggleTabPosition(id: galata.SidebarTabId): Promise<void> {
+    const tab = await this.getTab(id);
+
+    if (!tab) {
+      return;
+    }
+
+    await tab.click({ button: 'right' });
+
+    const switchMenuItem = await this.page.waitForSelector(
+      '.lm-Menu-content .lm-Menu-item[data-command="sidebar:switch"]',
+      { state: 'visible' }
+    );
+    if (switchMenuItem) {
+      await switchMenuItem.click();
+    }
+  }
+
+  /**
+   * Move all tabs to the left side
+   */
+  async moveAllTabsToLeft(): Promise<void> {
+    await this.page.evaluate(
+      async ({ pluginId }) => {
+        const settingRegistry = (await window.galata.getPlugin(
+          pluginId
+        )) as ISettingRegistry;
+        const SHELL_ID = '@jupyterlab/application-extension:shell';
+        const sidebars = {
+          Debugger: 'left',
+          'Property Inspector': 'left',
+          'Extension Manager': 'left',
+          'File Browser': 'left',
+          'Sessions and Tabs': 'left',
+          'Table of Contents': 'left'
+        };
+        const currentLayout = (await settingRegistry.get(
+          SHELL_ID,
+          'layout'
+        )) as any;
+        await settingRegistry.set(SHELL_ID, 'layout', {
+          single: { ...currentLayout.single, ...sidebars },
+          multiple: { ...currentLayout.multiple, ...sidebars }
+        });
+      },
+      {
+        pluginId:
+          '@jupyterlab/apputils-extension:settings' as keyof IPluginNameToInterfaceMap
+      }
+    );
+
+    await this.page.waitForFunction(() => {
+      const rightStack = document.getElementById('jp-right-stack');
+      return rightStack?.childElementCount === 0;
+    });
+  }
+
+  /**
+   * Get the handle on a given tab
+   *
+   * @param id Tab id
+   * @returns Tab handle
+   */
+  async getTab(
+    id: galata.SidebarTabId
+  ): Promise<ElementHandle<Element> | null> {
+    return await this.page.$(this.buildTabSelector(id));
+  }
+
+  /**
+   * Open a given tab
+   *
+   * @param id Tab id
+   */
+  async openTab(id: galata.SidebarTabId): Promise<void> {
+    const isOpen = await this.isTabOpen(id);
+    if (isOpen) {
+      return;
+    }
+
+    const tabButton = await this.page.$(this.buildTabSelector(id));
+    if (tabButton === null) {
+      throw new Error(`Unable to find the tab ${id} button`);
+    }
+    await tabButton.click();
+    await this._waitForTabActivate(tabButton);
+  }
+
+  /**
+   * Get the handle on a sidebar content panel
+   *
+   * @param side Position
+   * @returns Panel handle
+   */
+  async getContentPanel(
+    side: galata.SidebarPosition = 'left'
+  ): Promise<ElementHandle<Element> | null> {
+    return await this.page.$(
+      `#jp-${side}-stack .lm-StackedPanel-child:not(.lm-mod-hidden)`
+    );
+  }
+
+  /**
+   * Get the tab bar of the sidebar
+   *
+   * @param side Position
+   * @returns Tab bar handle
+   */
+  async getTabBar(
+    side: galata.SidebarPosition = 'left'
+  ): Promise<ElementHandle<Element> | null> {
+    return await this.page.$(`.jp-SideBar.jp-mod-${side}`);
+  }
+
+  /**
+   * Open a given sidebar
+   *
+   * @param side Position
+   */
+  async open(side: galata.SidebarPosition = 'left'): Promise<void> {
+    const isOpen = await this.isOpen(side);
+    if (isOpen) {
+      return;
+    }
+
+    await this.menu.clickMenuItem(
+      `View>Appearance>Show ${side === 'left' ? 'Left' : 'Right'} Sidebar`
+    );
+
+    await Utils.waitForCondition(async () => {
+      return await this.isOpen(side);
+    });
+  }
+
+  /**
+   * Close a given sidebar
+   *
+   * @param side Position
+   */
+  async close(side: galata.SidebarPosition = 'left'): Promise<void> {
+    const isOpen = await this.isOpen(side);
+    if (!isOpen) {
+      return;
+    }
+
+    await this.menu.clickMenuItem(
+      `View>Appearance>Show ${side === 'left' ? 'Left' : 'Right'} Sidebar`
+    );
+
+    await Utils.waitForCondition(async () => {
+      return !(await this.isOpen(side));
+    });
+  }
+
+  /**
+   * Get the selector for a given tab
+   *
+   * @param id Tab id
+   * @returns Selector
+   */
+  buildTabSelector(id: galata.SidebarTabId): string {
+    return `.lm-TabBar.jp-SideBar .lm-TabBar-content li.lm-TabBar-tab[data-id="${id}"]`;
+  }
+
+  protected async _waitForTabActivate(
+    tab: ElementHandle<Element>,
+    activate = true
+  ): Promise<void> {
+    await this.page.waitForFunction(
+      ({ tab, activate }) => {
+        const current = tab.classList.contains('lm-mod-current');
+        return activate ? current : !current;
+      },
+      { tab, activate }
+    );
+  }
+}

package/src/helpers/statusbar.ts

@@ -0,0 +1,56 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import { Page } from '@playwright/test';
+import { MenuHelper } from './menu';
+
+/**
+ * Status Bar helpers
+ */
+export class StatusBarHelper {
+  constructor(readonly page: Page, readonly menu: MenuHelper) {}
+
+  /**
+   * Whether the status bar is visible or not
+   *
+   * @returns Visibility status
+   */
+  async isVisible(): Promise<boolean> {
+    return await this.page.evaluate(() => {
+      const statusBar = document.querySelector(
+        '#jp-main-statusbar'
+      ) as HTMLElement;
+      return window.galata.isElementVisible(statusBar);
+    });
+  }
+
+  /**
+   * Show the status bar
+   */
+  async show(): Promise<void> {
+    const visible = await this.isVisible();
+    if (visible) {
+      return;
+    }
+
+    await this.menu.clickMenuItem('View>Show Status Bar');
+    await this.page.waitForSelector('#jp-main-statusbar', {
+      state: 'visible'
+    });
+  }
+
+  /**
+   * Hide the status bar
+   */
+  async hide(): Promise<void> {
+    const visible = await this.isVisible();
+    if (!visible) {
+      return;
+    }
+
+    await this.menu.clickMenuItem('View>Show Status Bar');
+    await this.page.waitForSelector('#jp-main-statusbar', {
+      state: 'hidden'
+    });
+  }
+}

package/src/helpers/style.ts

@@ -0,0 +1,100 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import { Page } from '@playwright/test';
+
+interface IUnusedStyleCheckOptions {
+  /**
+   * List of rule fragments to match rules for runtime checks.
+   */
+  fragments: string[];
+  /**
+   * List of fragments to filter out rules which cannot (easily) be checked at runtime.
+   */
+  exclude?: string[];
+  /**
+   * Whether to check rules with pseudo-classes.
+   *
+   * Default: false.
+   */
+  includePseudoClasses?: boolean;
+  /**
+   * Whether to include rules matching mod classes (`jp-mod-` and `.lm-mod-`).
+   *
+   * Default: false.
+   */
+  includeModifiers?: boolean;
+}
+
+/**
+ * CSS Style analysis helpers
+ */
+export class StyleHelper {
+  constructor(readonly page: Page) {}
+
+  /**
+   * Collect all CSS selectors on page.
+   */
+  async collectAllSelectors(): Promise<string[]> {
+    return this.page.evaluate(() =>
+      [...document.querySelectorAll('style')]
+        .filter(style => style.sheet !== null)
+        .map(style => [...style.sheet!.cssRules])
+        .flat()
+        .filter((rule: CSSRule) => rule instanceof CSSStyleRule)
+        .map((rule: CSSStyleRule) => rule.selectorText)
+    );
+  }
+
+  /**
+   * Find unused CSS rules.
+   *
+   * @param options spcify which rules to include/exclude.
+   * @returns List of rules with no matching elements on the page.
+   */
+  async findUnusedStyleRules(
+    options: IUnusedStyleCheckOptions
+  ): Promise<string[]> {
+    let exclude = typeof options.exclude !== 'undefined' ? options.exclude : [];
+    if (!options.includeModifiers) {
+      exclude = [...exclude, ...['.jp-mod-', '.lm-mod-']];
+    }
+    const relevantRules = (await this.collectAllSelectors())
+      // detection of pseudo-elements with `document.querySelector` is impossible,
+      // so we just check their parents
+      .map(selector =>
+        selector.replace(
+          /::?(after|before|backdrop|cue|cue-region|first-letter|first-line|file-selector-button|marker|placeholder|selection)/,
+          ''
+        )
+      )
+      .filter(selector =>
+        options.includePseudoClasses ? true : !selector.match(/:\w+/)
+      )
+      .filter(selector =>
+        options.fragments.some(fragment => selector.includes(fragment))
+      )
+      .filter(
+        selector => !exclude.some(fragment => selector.includes(fragment))
+      );
+    const potentiallyUnusedRules = await this.page.evaluate(
+      relevantRules =>
+        relevantRules.filter(
+          selector => document.querySelector(selector) == null
+        ),
+      relevantRules
+    );
+    if (potentiallyUnusedRules.length !== 0) {
+      console.log(
+        potentiallyUnusedRules.length,
+        'out of',
+        relevantRules.length,
+        'CSS rules for',
+        options.fragments,
+        'may be unused:',
+        potentiallyUnusedRules
+      );
+    }
+    return potentiallyUnusedRules;
+  }
+}

package/src/helpers/theme.ts

@@ -0,0 +1,50 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import { Page } from '@playwright/test';
+
+/**
+ * Theme helpers
+ */
+export class ThemeHelper {
+  constructor(readonly page: Page) {}
+
+  /**
+   * Set JupyterLab theme to Dark
+   */
+  async setDarkTheme(): Promise<void> {
+    await this.setTheme('JupyterLab Dark');
+  }
+
+  /**
+   * Set JupyterLab theme to Light
+   */
+  async setLightTheme(): Promise<void> {
+    await this.setTheme('JupyterLab Light');
+  }
+
+  /**
+   * Get JupyterLab theme name
+   *
+   * @returns Theme name
+   */
+  async getTheme(): Promise<string> {
+    return await this.page.evaluate(() => {
+      return document.body.dataset.jpThemeName as string;
+    });
+  }
+
+  /**
+   * Set JupyterLab theme
+   *
+   * @param themeName Theme name
+   */
+  async setTheme(themeName: string): Promise<void> {
+    const page = this.page;
+    await page.evaluate(async (themeName: string) => {
+      await window.galata.setTheme(themeName);
+    }, themeName);
+
+    await page.waitForSelector('#jupyterlab-splash', { state: 'detached' });
+  }
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Jupyter Development Team.
+// Copyright (c) Bloomberg Finance LP.
+// Distributed under the terms of the Modified BSD License.
+/**
+ * @packageDocumentation
+ * @module galata
+ */
+
+/**
+ * Export expect from playwright to simplify the import in tests
+ */
+export { expect } from '@playwright/test';
+
+export * from './extension';
+
+export * from './benchmarkReporter';
+export * from './galata';
+export * from './fixtures';
+export * from './jupyterlabpage';