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, butmamba
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 runningdoit 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 |
---|---|---|
|
|
a JSON array of tokens to pass to |
|
|
number of times to re-run failing tests |
|
|
where to start in the retry order |
|
|
which browser to use (only tested with FF) |
|
|
a custom |
|
|
skips a number of steps |
|
`` |
|
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 freshdist
)[ ] 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