jupyterlab / galata

JupyterLab UI Testing Framework

Installation | Documentation | Contributing | License | Team | Getting help |

JupyterLab

An extensible environment for interactive and reproducible computing, based on the Jupyter Notebook and Architecture.

JupyterLab is the next-generation user interface for Project Jupyter offering all the familiar building blocks of the classic Jupyter Notebook (notebook, terminal, text editor, file browser, rich outputs, etc.) in a flexible and powerful user interface.

JupyterLab can be extended using npm packages that use our public APIs. The prebuilt extensions can be distributed via PyPI, conda, and other package managers. The source extensions can be installed directly from npm (search for jupyterlab-extension) but require an additional build step. You can also find JupyterLab extensions exploring GitHub topic jupyterlab-extension. To learn more about extensions, see the user documentation.

Read the current JupyterLab documentation on ReadTheDocs.

Important

JupyterLab 3 will reach its end of maintenance date on May 15, 2024, anywhere on Earth. To help us make this transition, fixes for critical issues will still be backported until December 31, 2024. If you are still running JupyterLab 3, we strongly encourage you to upgrade to JupyterLab 4 as soon as possible. For more information, see JupyterLab 3 end of maintenance on the Jupyter Blog.

---

Getting started

Installation

If you use conda, mamba, or pip, you can install JupyterLab with one of the following commands.

• If you use conda:

  conda install -c conda-forge jupyterlab

• If you use mamba:

  mamba install -c conda-forge jupyterlab

• If you use pip:

  pip install jupyterlab

  If installing using pip install --user, you must add the user-level bin directory to your PATH environment variable in order to launch jupyter lab. If you are using a Unix derivative (e.g., FreeBSD, GNU/Linux, macOS), you can do this by running export PATH="$HOME/.local/bin:$PATH". If you are using a macOS version that comes with Python 2, run pip3 instead of pip.

For more detailed instructions, consult the installation guide. Project installation instructions from the git sources are available in the contributor documentation.

Installing with Previous Versions of Jupyter Notebook

When using a version of Jupyter Notebook earlier than 5.3, the following command must be run after installing JupyterLab to enable the JupyterLab server extension:

jupyter serverextension enable --py jupyterlab --sys-prefix

Running

Start up JupyterLab using:

jupyter lab

JupyterLab will open automatically in the browser. See the documentation for additional details.

If you encounter an error like "Command 'jupyter' not found", please make sure PATH environment variable is set correctly. Alternatively, you can start up JupyterLab using ~/.local/bin/jupyter lab without changing the PATH environment variable.

Prerequisites and Supported Browsers

The latest versions of the following browsers are currently known to work:

• Firefox
• Chrome
• Safari

See our documentation for additional details.

---

Getting help

We encourage you to ask questions on the Discourse forum. A question answered there can become a useful resource for others.

Bug report

To report a bug please read the guidelines and then open a Github issue. To keep resolved issues self-contained, the lock bot will lock closed issues as resolved after a period of inactivity. If a related discussion is still needed after an issue is locked, please open a new issue and reference the old issue.

Feature request

We also welcome suggestions for new features as they help make the project more useful for everyone. To request a feature please use the feature request template.

---

Development

Extending JupyterLab

To start developing an extension for JupyterLab, see the developer documentation and the API docs.

Contributing

To contribute code or documentation to JupyterLab itself, please read the contributor documentation.

JupyterLab follows the Jupyter Community Guides.

License

JupyterLab uses a shared copyright model that enables all contributors to maintain the copyright on their contributions. All code is licensed under the terms of the revised BSD license.

Team

JupyterLab is part of Project Jupyter and is developed by an open community. The maintenance team is assisted by a much larger group of contributors to JupyterLab and Project Jupyter as a whole.

JupyterLab's current maintainers are listed in alphabetical order, with affiliation, and main areas of contribution:

• Mehmet Bektas, Netflix (general development, extensions).
• Alex Bozarth, IBM (general development, extensions).
• Eric Charles, Datalayer, (general development, extensions).
• Frédéric Collonval, WebScIT (general development, extensions).
• Martha Cryan, Mito (general development, extensions).
• Afshin Darian, QuantStack (co-creator, application/high-level architecture, prolific contributions throughout the code base).
• Vidar T. Fauske, JPMorgan Chase (general development, extensions).
• Brian Granger, AWS (co-creator, strategy, vision, management, UI/UX design, architecture).
• Jason Grout, Databricks (co-creator, vision, general development).
• Michał Krassowski, Quansight (general development, extensions).
• Max Klein, JPMorgan Chase (UI Package, build system, general development, extensions).
• Gonzalo Peña-Castellanos, QuanSight (general development, i18n, extensions).
• Fernando Perez, UC Berkeley (co-creator, vision).
• Isabela Presedo-Floyd, QuanSight Labs (design/UX).
• Steven Silvester, MongoDB (co-creator, release management, packaging, prolific contributions throughout the code base).
• Jeremy Tuloup, QuantStack (general development, extensions).

Maintainer emeritus:

• Chris Colbert, Project Jupyter (co-creator, application/low-level architecture, technical leadership, vision, PhosphorJS)
• Jessica Forde, Project Jupyter (demo, documentation)
• Tim George, Cal Poly (UI/UX design, strategy, management, user needs analysis).
• Cameron Oelsen, Cal Poly (UI/UX design).
• Ian Rose, Quansight/City of LA (general core development, extensions).
• Andrew Schlaepfer, Bloomberg (general development, extensions).
• Saul Shanabrook, Quansight (general development, extensions)

This list is provided to give the reader context on who we are and how our team functions. To be listed, please submit a pull request with your information.

---

Weekly Dev Meeting

We have videoconference meetings every week where we discuss what we have been working on and get feedback from one another.

Anyone is welcome to attend, if they would like to discuss a topic or just listen in.

• When: Wednesdays 9:00 AM Pacific Time (USA)
• Where: jovyan Zoom
• What: Meeting notes

Notes are archived on GitHub Jupyter Frontends team compass.

galata's Issues

Support for alternate JupyterLab distributions

Problem

It would be great if galata could also be used to test alternative JupyterLab distributions such as RetroLab.

Proposed Solution

At the moment it looks like the default page hits the /lab endpoint:

galata/packages/galata/jest-env.js

Line 179 in ba2713f

let jlabUrl = path.join(baseUrl, 'lab');

There is also this setup logic using /lab by default:

galata/packages/galata/jest-env.js

Lines 143 to 149 in ba2713f

	let resourcePath = '/lab';
	if (context.jlabWorkspace) {
	resourcePath = `${resourcePath}/workspaces/${context.jlabWorkspace}`;
	}
	await context.page.evaluate(async resourcePath => {
	await window.galataip.waitForLaunch(resourcePath);
	}, resourcePath);

Additional context

A potential candidate for this would be RetroLab: jupyterlab/retrolab#135

Galata appears to not work with JupyterLab 3.0.9

When using Galata with JupyterLab 3.0.9 I am having the following error in the terminal running Galata:

yarn run v1.22.10
$ galata
 LOG  Deleting existing test output directory 'test'
Determining test suites to run...

 LOG  Using Galata built for JupyterLab version 3.0.3
 LOG  Failed to inject galataip object into browser context

 RUNS  tests/widgets.test.ts
 LOG  jest output not found
 LOG  galata output not found
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

And at the same moment I am getting the following error in the terminal running jupyterlab:

[E 2021-03-29 15:03:37.662 ServerApp] Uncaught exception GET /lab/api/settings/@jupyterlab/docmanager-extension:plugin?1617023016487 (::1)
    HTTPServerRequest(protocol='http', host='localhost:8888', method='GET', uri='/lab/api/settings/@jupyterlab/docmanager-extension:plugin?1617023016487', version='HTTP/1.1', remote_ip='::1')
    Traceback (most recent call last):
      File "/home/martin/miniconda3/envs/bqplot/lib/python3.9/site-packages/tornado/web.py", line 1704, in _execute
        result = await result
    tornado.iostream.StreamClosedError: Stream is closed

From galata using playwright to playwright with galata

Problem

playwright is an amazing tool with a strong support from Microsoft and the community. So we can only expect it to grow in reliability and ease of usage. In particular with v1.12 a test runner was released with the builtin ability to compare image, generate trace, create videos, running tests in parallel, fixtures, reporters,... . I think we should onboard that as there is no value for us to try keeping up the pace by hiding the tool.

Proposed Solution

• Embrace playwright test runner
  • Port current report generator to be a valid playwright reporter
  • Unlock the ability to create test from the code generator tool by copy-paste

while keeping the nice helpers functions.

Rendering artifacts lead to false positive

Description

I'm seeing false positives, described at spacetelescope/jdaviz#543 (comment) . The capture of the output cells seems ok, but it seems to be capturing a part of the Jupyter Lab 3.0 interface (with different portions grey each time). I'm not sure this is a user bug or a Galata bug.

Add theme option

It would be nice to be able to select the theme with a command-line option, something like:

galata --theme=dark

Format with ESLint and Prettier

As mentioned in #48, we should adopt ESLint and Prettier to format the code base, so it's consistent with the tooling already in place in the main JupyterLab repo.

notebook.createNew should wait for rename properly

Description

notebook.createNew is not waiting enough if a name is set

Improve Image Diff viewer in result report

Support for side-by-side view, swipe and transition like GitHub PR image diff would be great

--update-references could maybe create the reference directory

When running --update-references for the first time, the command fails with:

Reference directory './reference-output' does not exist.
error Command failed with exit code 1.

Maybe Galata could automatically create the reference directory if it doesn't exist?

Allow for custom tab bar ids

Problem

For now the set of tab bar ids is defined here:

galata/packages/galata/src/galata.ts

Line 100 in d717e6a

type SidebarTabId = 'filebrowser' | 'jp-running-sessions' | 'tab-manager' | 'jp-property-inspector' | 'table-of-contents' | 'extensionmanager.main-view' | 'jp-debugger-sidebar';

It would be great if this could be made configurable, or be able to pass any id.

For example the @jupyterlab/git extension adds a panel to the left area, and this extension could use galata for end to end testing.

Proposed Solution

Allow arbitrary ids (as strings)?

Additional context

Related to #45

Archive the repository

With jupyterlab/jupyterlab#10796 now merged upstream, we should be able to archive this repo to clearly communicate where the main development is happening.

TODO

• Transfer relevant issues to https://github.com/jupyterlab/jupyterlab
• Add an archive header to the README.md: #82
• Archive the repo

Automate releases

Since releasing Galata only consists in publishing the package to npm, it should be possible to automate this workflow.

Either with a simple GitHub Actions workflow.

Or using the Jupyter Releaser: https://github.com/jupyter-server/jupyter_releaser

Consider using playwright?

Opening a new issue to discuss potential ideas for the next iterations.

I've been trying out playwright lately and it's been really nice. It's also great that chromium, firefox and webkit are all supported by default.

Since the playwright api is very similar to puppeteer (and the same for the 3 browser), maybe it's worth considering it in the future?

The change would most likely be about updating imports, and maybe also about simplifying selectors. The galata cli could also be extended to configure browsers, so they could be set as matrix items on CI.

More robust way to move items to the left area

A more robust fix could be to retrieve all the items programmatically instead of manually overriding them with overrides["id"] = "left";

Originally posted by @jtpio in #45 (comment)

Toggling simple mode should wait for switch animation to end

Description

Toggling simple mode doesn't always wait enough for switch widget's animation to end.

Reproduce

Randomly reproduces with toggleSimpleMode API method.

Expected behavior

Should wait for switch animation to end.

Update the JupyterLab version

Currently Galata targets 3.0.7:

galata/packages/galata/bin/metadata.json

Line 1 in 3839864

{"jlabVersion":"3.0.7"}

We should consider updating to 3.0.16.

Publish to npm

We should publish galata to npm, so it can easily be added as a dependency in other projects, list the galata example:

galata/packages/galata-example/package.json

Line 12 in 1bae028

"@jupyterlab/galata": "3.0.3-1"

Things to check before releasing:

• Release strategy: how often and when (depending on the JupyterLab release cycle?)
• Versioning
• API breaking changes

Fix top-level version in `package.json` for the releaser

Description

The top-level version added in #72 was used mostly as a placeholder so it can be npm pack.

galata/package.json

Line 3 in 7500160

"version": "0.1.0",

However it ended as the version added to the changelog:

Reproduce

In the automated changelog entry in #73, it picked up 0.1.0 as the version instead of 3.0.11-3 as specified in the workflow.

Probably we could sync the lerna version with the top-level one in package.json

Can't connect to WS after launching separate headless chrome instance

Description

I'm able to run galata fine as long as I don't specify my own browser. Otherwise the process just hangs. I've tried running:

node ./node_modules/.bin/galata "--browser-url" "http://localhost:9222" --browser-type chromium

This might be related to this issue: microsoft/playwright#4054
But I've tried replacing connect in Galata source code with connectOverCDP but without success.

Create RELEASE.md

We should add a RELEASE.md at the top level of the repo, that will list the steps for releasing a new version of Galata.

The file would also explain how to version Galata, and when to upgrade for new version of JupyterLab (#29 could be a reference).

Support / documentation for Linux users

Really nice library, thanks for putting that together!

At the moment it looks like the chrome path defaults to the one for Mac when using galata on Linux:

https://github.com/mbektasbbg/galata/blob/91f99885a0be2da7c048d587d9ccf697773b180a/packages/galata/bin/cli.js#L142-L144

Wondering whether it should be the default? Or maybe default to /usr/bin/chromium or which chromium?

Otherwise a small section in the documentation / readme could be enough as a starting point.

Switch from npm to yarn (or jlpm) for development

To make the tooling consistent across the @jupyterlab repositories, we should consider using yarn or jlpm instead of npm to manage dependencies and run scripts.

This would then also mean replacing the existing package-lock.json by a new yarn.lock.

Rename the default branch to main

I was under the impression this was already the case since this is a new repo, but it could be that it was created a while ago when main was not the default on GitHub yet.

How about renaming the default master branch to main? It should be possible to do that easily via the settings menu.

Now would be a good time since there is no open PRs so it shouldn't be too disruptive.

galata on CI

For now it looks like galata uses puppeteer-core:

https://github.com/mbektasbbg/galata/blob/91f99885a0be2da7c048d587d9ccf697773b180a/packages/galata/src/jlabtest.ts#L4

Which requires specifying the path to a Chrome binary.

Should there also be support for running galata in environments where an existing Chrome might not be available? For example on CI.