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

`mamba`#

mamba install -c conda-forge robotframework-jupyterlibrary

conda also works, usually, but mamba is both faster and provides better error messages when things go wrong.

`main`#

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

Start with a sensible, activated base like Mambaforge. Mixing the miniconda or anaconda distributions’ defaults (e.g. anaconda.com is a recipe for disaster, and may violate the terms of service).

Here’s a complete setup:

mamba create \
  # using `--prefix=.venv` is also useful for having predictable file locations, but can confuse IDEs
  --name testing-jupyter \
  --channel conda-forge \ 
  # CPython 3.8+ required, not tested with pypy, or (near) end-of-life CPython  
  python=3 \
  jupyterlab \
  robotframework-seleniumlibrary \
  geckodriver \
  # using a Long Term Support (LTS) Firefox is useful for avoiding "only works in Chrome"
  firefox

Activate the environment:

source activate testing-jupyter

Install “hot” dependencies:

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

Contributing to JupyterLibrary#

Get `CONDA_EXE`#

Get Mambaforge

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.8 with jupyterlab 3 failed:

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

Or, in a bat script:

@echo on
set RFJL_LOCKDIR=test/win-64/py3.8/lab3
doit release

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

Environment Variables#

A number of environment variables control how some of the doit tasks function.

variable	default	note
`ATEST_ARGS`	`[]`	a JSON array of tokens to pass to `pabot`
`ATEST_RETRIES`	`0`	number of times to re-run failing tests
`ATEST_ATTEMPT`	`0`	where to start in the retry order
`BROWSER`	`headlessfirefox`	which browser to use (only tested with FF)
`CONDA_EXE`	`mamba`	a custom `conda`-compatible tool to use
`IN_BINDER`	`0`	skips a number of steps
`INSTALL_ARTIFACT`	``	`pip install` a built artifact instead of editable

Releasing#

[ ] merge all outstanding PRs
[ ] start a release issue with a checklist (maybe like this one)
[ ] ensure pyproject.toml#/project/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 main
[ ] 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 pyproject.toml#/project/version to next development version
- [ ] update release procedures

Appendix: Current `doit` tasks#

doit is used heavily in development and continuous integration.

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:robocop                        ensure robot code is well-behaved
lint:robotidy                       ensure robot code is well-formatted
lint:ruff                           ensure python code is well-behaved
lint:ssort                          apply source ordering to python
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_11__lab3   lock the test environment for linux-64 (ft. py3.11, lab3)
lock:test__linux-64__py3_11__lab4   lock the test environment for linux-64 (ft. py3.11, lab4)
lock:test__linux-64__py3_8__lab3    lock the test environment for linux-64 (ft. py3.8, lab3)
lock:test__linux-64__py3_8__lab4    lock the test environment for linux-64 (ft. py3.8, lab4)
lock:test__osx-64__py3_11__lab3     lock the test environment for osx-64 (ft. py3.11, lab3)
lock:test__osx-64__py3_11__lab4     lock the test environment for osx-64 (ft. py3.11, lab4)
lock:test__osx-64__py3_8__lab3      lock the test environment for osx-64 (ft. py3.8, lab3)
lock:test__osx-64__py3_8__lab4      lock the test environment for osx-64 (ft. py3.8, lab4)
lock:test__win-64__py3_11__lab3     lock the test environment for win-64 (ft. py3.11, lab3)
lock:test__win-64__py3_11__lab4     lock the test environment for win-64 (ft. py3.11, lab4)
lock:test__win-64__py3_8__lab3      lock the test environment for win-64 (ft. py3.8, lab3)
lock:test__win-64__py3_8__lab4      lock the test environment for win-64 (ft. py3.8, lab4)
publish                             Publish distributioons.
publish:pypi                        upload python sdist and wheel to PyPI
release                             Run the full set of tasks needed for a new release.
report                              Generate reports of test data.
report:cov:combine                  gather coverage
report:cov:html:rfjl                generate coverage html
report:cov:html:rfsl                generate coverage html
report:cov:html:se                  generate coverage html
report:cov:report                   emit coverage console report and check
report:robot:combine                combine all robot outputs into a single HTML report
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:dryrun                         pass the tests through the robot machinery, but don't actually _run_ anything