INSTALL#

Installing JupyterLibrary will bring along Robot Framework and SeleniumLibrary. Jupyter components, like notebook, jupyterlab and nteract_on_jupyter, and browser executors (e.g. chromedriver, geckodriver) and various utilities (e.g. nodejs) are up to you, depending on what you want to test. Here are some examples.

pip#

pip install robotframework-jupyterlibrary

conda#

conda install -c conda-forge robotframework-jupyterlibrary

master#

JupyterLibrary is under active development, and is heavily invested in conda because of the complexity of managing browser execution dependencies. But conda (rightly) makes it hard to install Random Repos from the Internet, so you’ll need a bit of pip, too.

Here’s a complete setup:

conda create --name testing-jupyter --channel conda-forge 
  python=3 \   # 3.7 required, not tested with pypy  
  jupyterlab \
  robotframework-seleniumlibrary \
  geckodriver \
  firefox

conda activate testing-jupyter

pip install \
  --no-deps \             # don't want any surprises
  --ignore-installed \    # just to be sure
  git+http://github.com/robots-from-jupyter/robotframework-jupyterlibrary

Contributing to JupyterLibrary#

Get CONDA_EXE#

mamba install -c conda-forge doit
# optional meta-dependency
mamba install -c conda-forge conda-lock

Get the code#

git clone http://github.com/robots-from-jupyter/robotframework-jupyterlibrary
cd robotframework-jupyterlibrary

Doit#

Listing all the tasks#

doit list

Just run (just about) everything#

doit release

Lock Files#

After adding/changing any dependencies in .github/env_specs, the lockfiles need to be refreshed in .github/locks and committed.

doit lock

Bootstrapping from no lockfiles requires an external provider of conda-lock. It may require running doit lock a few times to get a stable set of environment solutions.

Reproducing CI failures#

By default, the doit scripts use the lockfile most like where you are developing, hoping for a better cache hit rate. On the same operating system, however, any of the pre-solved lockfiles can be used, by specifying the RJFL_LOCKFILE environment variable.

For example, if linux-64 running python3.7 with jupyterlab 1 failed:

!/usr/bin/env bash
set -eux
RFJL_LOCKDIR=test/linux-64/py3.7/lab1 doit release

Or, in a bat script:

@echo on
set RFJL_LOCKDIR=test/win-64/py3.7/lab1
doit release

This will recreate the test environment with the specified lockfile, and repeat all the steps.

Releasing#

  • [ ] merge all outstanding PRs

  • [ ] start a release issue with a checklist (maybe like this one)

  • [ ] ensure VERSION has been increased appropriately

  • [ ] ensure the HISTORY.ipynb is up-to-date

  • [ ] validate on binder

  • [ ] validate on ReadTheDocs

  • [ ] wait for a successful build of master

  • [ ] download the dist archive and unpack somewhere (maybe a fresh dist)

  • [ ] create a new release through the GitHub UI

    • [ ] paste in the relevant HISTORY entries

    • [ ] upload the artifacts

  • [ ] actually upload to pypi.org

    doit publish

  • [ ] postmortem

    • [ ] handle conda-forge feedstock tasks

    • [ ] validate on binder via simplest-possible gists

    • [ ] activate the version on ReadTheDocs

    • [ ] bump VERSION to next development version

    • [ ] update release procedures

Appendix: Current tasks#

binder                              get to a basic interactive state
build                               build packages
build:hash                          generate a hash file of all distributions
build:pypi                          build the pypi sdist/wheel
conda_build                         build conda package
conda_build:build                   use boa to build the conda package
conda_build:recipe                  update the conda recipe
docs                                build HTML docs
docs:rtd:env                        generate a readthedocs-compatible env
docs:sphinx                         build the docs with sphinx
env                                 
env:docs                            create the local docs environment
env:lint                            create the local lint environment
env:meta                            create the local meta environment
env:test                            create the local test environment
js                                  javascript cruft
js:yarn                             install nodejs dev dependencies
lab                                 start a jupyter lab server (with all other extensions)
lab:serve                           runs lab (never stops)
lint                                lint code
lint:black                          ensure python code is well-formatted
lint:prettier                       ensure markdown, YAML, JSON, etc. are well-formatted
lint:pyflakes                       ensure python code is well-behaved
lint:robocop                        ensure robot code is well-behaved
lint:robotidy                       ensure robot code is well-formatted
lock                                generate conda lock files for all the excursions
lock:docs__linux-64                 lock the docs environment for linux-64 []
lock:docs__osx-64                   lock the docs environment for osx-64 []
lock:docs__win-64                   lock the docs environment for win-64 []
lock:lint__linux-64                 lock the lint environment for linux-64 []
lock:lint__osx-64                   lock the lint environment for osx-64 []
lock:lint__win-64                   lock the lint environment for win-64 []
lock:meta__linux-64                 lock the meta environment for linux-64 []
lock:meta__osx-64                   lock the meta environment for osx-64 []
lock:meta__win-64                   lock the meta environment for win-64 []
lock:test__linux-64__py3_10__lab1   lock the test environment for linux-64 (ft. py3.10, lab1)
lock:test__linux-64__py3_10__lab2   lock the test environment for linux-64 (ft. py3.10, lab2)
lock:test__linux-64__py3_10__lab3   lock the test environment for linux-64 (ft. py3.10, lab3)
lock:test__linux-64__py3_7__lab1    lock the test environment for linux-64 (ft. py3.7, lab1)
lock:test__linux-64__py3_7__lab2    lock the test environment for linux-64 (ft. py3.7, lab2)
lock:test__linux-64__py3_7__lab3    lock the test environment for linux-64 (ft. py3.7, lab3)
lock:test__osx-64__py3_10__lab1     lock the test environment for osx-64 (ft. py3.10, lab1)
lock:test__osx-64__py3_10__lab2     lock the test environment for osx-64 (ft. py3.10, lab2)
lock:test__osx-64__py3_10__lab3     lock the test environment for osx-64 (ft. py3.10, lab3)
lock:test__osx-64__py3_7__lab1      lock the test environment for osx-64 (ft. py3.7, lab1)
lock:test__osx-64__py3_7__lab2      lock the test environment for osx-64 (ft. py3.7, lab2)
lock:test__osx-64__py3_7__lab3      lock the test environment for osx-64 (ft. py3.7, lab3)
lock:test__win-64__py3_10__lab1     lock the test environment for win-64 (ft. py3.10, lab1)
lock:test__win-64__py3_10__lab2     lock the test environment for win-64 (ft. py3.10, lab2)
lock:test__win-64__py3_10__lab3     lock the test environment for win-64 (ft. py3.10, lab3)
lock:test__win-64__py3_7__lab1      lock the test environment for win-64 (ft. py3.7, lab1)
lock:test__win-64__py3_7__lab2      lock the test environment for win-64 (ft. py3.7, lab2)
lock:test__win-64__py3_7__lab3      lock the test environment for win-64 (ft. py3.7, lab3)
publish                             publish distributioons
publish:pypi                        upload python sdist and wheel to PyPI
release                             the full set of tasks needed for a new release
setup                               
setup:docs                          [docs] python development install
setup:lint                          [lint] python development install
setup:test                          [test] python development install
test                                (dry)run tests
test:atest                          run acceptance tests with robot
test:combine                        combine all robot outputs into a single HTML report
test:dryrun                         pass the tests through the robot machinery, but don't actually _run_ anything