notebook/CONTRIBUTING.md

Contributing to RetroLab

Thanks for contributing to RetroLab!

Make sure to follow Project Jupyter's Code of Conduct for a friendly and welcoming collaborative environment.

Setting up a development environment

Note: You will need NodeJS to build the extension package.

The jlpm command is JupyterLab's pinned version of yarn that is installed with JupyterLab. You may use yarn or npm in lieu of jlpm below.

Note: we recomment using mamba to speed the creating of the environment.

# create a new environment
mamba create -n retrolab -c conda-forge python nodejs -y

# activate the environment
conda activate retrolab

# Install package in development mode
pip install -e .

# Link the RetroLab JupyterLab extension and RetroLab schemas
jlpm develop

# Enable the server extension
jupyter server extension enable retrolab

retrolab follows a monorepo structure. To build all the packages at once:

jlpm build

There is also a watch script to watch for changes and rebuild the app automatically:

jlpm watch

To make sure the retrolab server extension is installed:

$ jupyter server extension list
Config dir: /home/username/.jupyter

Config dir: /home/username/miniforge3/envs/retrolab/etc/jupyter
    jupyterlab enabled
    - Validating jupyterlab...
      jupyterlab 3.0.0 OK
    retrolab enabled
    - Validating retrolab...
      retrolab 0.1.0rc2 OK
    nbclassic enabled
    - Validating nbclassic...
      nbclassic  OK

Config dir: /usr/local/etc/jupyter

Then start RetroLab with:

jupyter retro

Running Tests

To run the tests:

jlpm run build:test
jlpm run test

There are also end to end tests to cover higher level user interactions, located in the ui-tests folder. To run these tests:

cd ui-tests
# start a new Jupyter server in a terminal
jlpm start

# in a new terminal, run the tests
jlpm test

The test script calls the Playwright test runner. You can pass additional arguments to playwright by appending parameters to the command. For example to run the test in headed mode, jlpm test --headed.

Checkout the Playwright Command Line Reference for more information about the available command line options.

Running the end to end tests in headful mode will trigger something like the following: