Instructions for running in CI

Changes.md

@@ -2,6 +2,11 @@
 
 Note: development is tracked on the [`develop` branch](https://github.com/chmp/ipytest/tree/develop).
 
+## `develop`
+
+- Add a description how to use `IPytest` in CI context. Thanks
+  [MusicalNinjaDad](https://github.com/MusicalNinjaDad) for the contribution
+
 ## `0.14.2`
 
 - Support collecting branch coverage in notebooks (e.g., via `--cov--branch`)

Readme.md

@@ -42,6 +42,42 @@ This command will first delete any previously defined tests, execute the cell
 and then run pytest. For further details on how to use `ipytest` see the
 [**example notebook**](./Example.ipynb) or the [reference](#reference) below.
 
+### Enabling by default for all notebooks
+
+[IPython startup scripts][ci-ipy-startup-scripts] allow to customize the interpreter,
+for example to import and configure ipytest by default.Their location can be configured
+via the `IPYTHONDIR` environment variable.
+
+[ci-ipy-startup-scripts]: https://ipython.readthedocs.io/en/stable/interactive/tutorial.html#startup-files
+
+### Running in CI
+
+To run notebook tests in a CI workflow, you may want to
+
+1. Set `raise_on_error=True` to ensure any `pytest` errors raise exceptions visible to the CI
+   system. For example via
+
+    ```python
+    import ipytest
+    ipytest.autoconfig(raise_on_error=True)
+    ```
+
+2. Execute the notebooks with [`nbval`](https://github.com/computationalmodelling/nbval). The
+   `--nbval-lax` flag allows to only check for errors, not the exact notebook output which is likely
+   to change between `pytest` runs
+
+To only set `raise_on_error=True` in CI systems you can check for common environment variables. See
+[cibuildwheel.ci.detect_ci_provider][ci-detect_ci_provider] for a listing. For example
+
+```python
+import ipytest
+import os
+
+ipytest.autoconfig(raise_on_error="GITHUB_ACTIONS" in os.environ)
+```
+
+[ci-detect_ci_provider]: https://github.com/pypa/cibuildwheel/blob/c93d51ec540da7537ae66107a32c60dccd705102/cibuildwheel/ci.py#L21
+
 ## Global state
 
 There are multiple sources of global state when using pytest inside the notebook: