add notebook tests

.github/workflows/build.yml

@@ -22,17 +22,18 @@ jobs:
 
     - name: Get prerelease version tags
       if: env.IS_PRERELEASE == 'true'
+      id: prerelease-check
       run: |
         py_dirty_tag=$(awk '/__version__ = "[[:digit:]+]\.[[:digit:]+]\.[[:digit:]+]\-.+"/ {print $3}' ./mols2grid/_version.py)
         py_is_pre=$(test -z "$py_dirty_tag" && echo "false" || echo "true")
         js_version_string=$(grep '"version":' ./package.json)
         js_dirty_tag=$(echo "$js_version_string" | cut -d- -f2)
         js_is_pre=$(test "$js_version_string" == "$js_dirty_tag" && echo "false" || echo "true")
-        echo "py_is_pre=$py_is_pre" >> $GITHUB_ENV
-        echo "js_is_pre=$js_is_pre" >> $GITHUB_ENV
+        echo "py=$py_is_pre" >> $GITHUB_OUTPUT
+        echo "js=$js_is_pre" >> $GITHUB_OUTPUT
 
     - name: Fail if prerelease is not correctly versioned
-      if: (env.IS_PRERELEASE == 'true') && !( env.py_is_pre && env.js_is_pre )
+      if: (env.IS_PRERELEASE == 'true') && !( steps.prerelease-check.outputs.py && steps.prerelease-check.outputs.js )
       uses: actions/github-script@v3
       with:
         script: |

.github/workflows/ci.yml

@@ -19,32 +19,20 @@ concurrency:
 jobs:
   tests:
     name: ${{ matrix.label }}
-    runs-on: ${{ matrix.os }}
+    runs-on: ubuntu-latest
     strategy:
       matrix:
         include:
           - label: CI-old
-            os: ubuntu-latest
             python-version: 3.8
             extra_dependencies: "rdkit==2020.03.1 boost-cpp=1.72.0=h359cf19_6"
           - label: CI-edge
-            os: ubuntu-latest
             python-version: "3.10"
             extra_dependencies: "rdkit"
-          - label: CI-py3.9-rdkit2022
-            os: ubuntu-latest
-            python-version: 3.9
-            extra_dependencies: "rdkit==2022.03.1"
 
     steps:
       - uses: actions/checkout@v3
 
-      - name: Install node
-        uses: actions/setup-node@v3
-        with:
-          node-version: 18
-          cache: "yarn"
-
       - name: Install Firefox
         uses: browser-actions/setup-firefox@latest
 
@@ -64,14 +52,26 @@ jobs:
         with:
           path: ~/conda_pkgs_dir
           key:
-            conda-${{ hashFiles('environment.yml') }}-${{ matrix.label }}-${{ env.CACHE_NUMBER }}
+            conda-${{ hashFiles('tests/environment.yml') }}-${{ matrix.label }}-${{ env.CACHE_NUMBER }}
 
       - name: Cache pip
         uses: actions/cache@v3
         with:
           path: ~/.cache/pip
-          key: pip-${{ hashFiles('setup.cfg') }}
+          key: pip-${{ hashFiles('pyproject.toml') }}
           restore-keys: pip-
+
+      - name: Get yarn cache directory path
+        id: yarn-cache-dir-path
+        run: echo "dir=$(yarn cache dir)" >> $GITHUB_OUTPUT
+
+      - name: Cache yarn
+        uses: actions/cache@v3
+        with:
+          path: ${{ steps.yarn-cache-dir-path.outputs.dir }}
+          key: yarn-${{ hashFiles('yarn.lock') }}
+          restore-keys: |
+            yarn-
 
       - name: Setup Conda
         uses: conda-incubator/setup-miniconda@v2
@@ -93,13 +93,15 @@ jobs:
 
       - name: Install remaining conda dependencies
         run: |
-          mamba install ${{ matrix.extra_dependencies }}
+          mamba install jupyterlab ipywidgets=7 ${{ matrix.extra_dependencies }}
           mamba list
 
-      - name: Install package through pip
+      - name: Build and install package
         run: |
           pip install .[tests,build]
+          jupyter labextension develop . --overwrite
           pip list
+          jupyter labextension list
       
       - name: Run tests
         run: |
@@ -143,3 +145,108 @@ jobs:
         run: |
           pip install dist/mols2grid-*.whl
           python test_install.py
+
+  notebook-tests:
+    name: ${{ matrix.label }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - label: JLab-3-Widgets-7
+            extra_dependencies: "jupyterlab>=3.2 ipywidgets=7"
+          - label: JLab-4-Widgets-8
+            extra_dependencies: "jupyterlab=4 ipywidgets=8"
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Cache conda
+        uses: actions/cache@v3
+        env:
+          CACHE_NUMBER: 0
+        with:
+          path: ~/conda_pkgs_dir
+          key:
+            conda-${{ hashFiles('tests/environment.yml') }}-${{ matrix.label }}-${{ env.CACHE_NUMBER }}
+
+      - name: Cache pip
+        uses: actions/cache@v3
+        with:
+          path: ~/.cache/pip
+          key: pip-${{ hashFiles('pyproject.toml') }}
+          restore-keys: pip-
+
+      - name: Get yarn cache directory path
+        id: yarn-ui-cache-dir-path
+        run: echo "dir=$(yarn cache dir)" >> $GITHUB_OUTPUT
+
+      - name: Cache yarn
+        uses: actions/cache@v3
+        with:
+          path: ${{ steps.yarn-ui-cache-dir-path.outputs.dir }}
+          key: yarn-ui-${{ hashFiles('tests/notebooks/yarn.lock') }}
+          restore-keys: |
+            yarn-ui-
+
+      - name: Setup Conda
+        uses: conda-incubator/setup-miniconda@v2
+        with:
+          python-version: "3.10"
+          environment-file: tests/environment.yml
+          use-only-tar-bz2: true
+          miniforge-variant: Mambaforge
+          miniforge-version: latest
+          use-mamba: true
+
+      - name: Install remaining conda dependencies
+        run: |
+          mamba install jupyter-packaging~=0.10 rdkit ${{ matrix.extra_dependencies }}
+          mamba list
+
+      - name: Build the extension
+        run: |
+          jlpm
+          jlpm build
+          pip install -e .[build]
+          jupyter labextension develop . --overwrite
+          jupyter labextension list
+
+      - name: Install Test Dependencies
+        run: |
+          npx playwright install chromium
+        working-directory: tests/notebooks
+
+      - name: Execute integration tests
+        shell: bash -l {0}
+        working-directory: tests/notebooks
+        run: |
+          npx playwright test
+
+      - name: Upload Playwright Test assets
+        if: always()
+        uses: actions/upload-artifact@v3
+        with:
+          name: notebooks-test-assets
+          path: |
+            tests/notebooks/test-results
+
+      - name: Upload Playwright Test report
+        if: always()
+        uses: actions/upload-artifact@v3
+        with:
+          name: notebooks-test-report
+          path: |
+            tests/notebooks/playwright-report
+
+      - name: Update snapshots
+        if: failure()
+        working-directory: tests/notebooks
+        run: |
+          jlpm test:update
+
+      - name: Upload updated snapshots
+        if: failure()
+        uses: actions/upload-artifact@v3
+        with:
+          name: notebook-updated-snapshots
+          path: tests/notebooks/tests

DEVELOPMENT.md

@@ -1,13 +1,14 @@
 This is a short guide to setup a dev environment for mols2grid.
 
 1. Install conda or mamba
-2. Create a new environment. Python 3.7+ (prefer 3.8):
+2. Create a new environment. Python 3.8+ (prefer 3.10):
    ```
    conda env create --name mols2grid --file docs/environment.yml
    ```
 3. Install all the package dependencies in editable mode:
    ```
    pip install -e .[dev]
+   jupyter labextension develop . --overwrite
    ```
 
 To run tests locally:

docs/contents.md

@@ -17,9 +17,8 @@
 
 # 🐍 Installation
 ---
-
-mols2grid was developped for Python 3.7+ and requires rdkit (>=2020.03.1), pandas and jinja2 as dependencies.  
-The easiest way to install it is from conda:
+
+The easiest way to install `mols2grid` is from conda:
 ```shell
 conda install -c conda-forge mols2grid
 ```
@@ -29,9 +28,24 @@ Alternatively, you can also use pip:
 pip install rdkit mols2grid
 ```
 
-If you notice that the selections, callbacks and interactive filtering aren't working as intended, you may have to manually activate the extension:
-- for Jupyter Lab: `jupyter labextension install mols2grid`
-- for Jupyter Notebook: `jupyter nbextension install mols2grid`
+## Troubleshooting
+
+If you see a JavaScript error message such as:
+```text
+Failed to load model class 'MolGridModel' from module 'mols2grid'
+Error: Module mols2grid, version XXX is not registered, however, YYY is
+```
+
+Or if you notice that the selections, callbacks and interactive filtering aren't working as intended, you may have to manually activate the extension:
+
+```shell
+jupyter labextension enable mols2grid
+```
+
+You should also make sure that you have installed compatible versions of `ipywidgets` and the
+`jupyterlab`/`notebook` stack. The following specs are currently supported:
+- `ipywidgets=7`, `jupyterlab=3`, `notebook=6`
+- `ipywidgets=8`, `jupyterlab=4`, `notebook=7`
 
 **Compatibility**
 

docs/environment.yml

@@ -3,19 +3,16 @@ channels:
   - conda-forge
   - defaults
 dependencies:
-  - ipykernel==6.26.0
-  - ipywidgets==7.8.0
-  - notebook<7.0.0
+  - ipywidgets=7
+  - notebook=7
   - mistune<3.0.0
-  - jedi==0.19.1
-  - jinja2==3.1.2
   - nbsphinx==0.8.8
-  - nodejs==18.18.2
-  - pandas==2.1.4
+  - nodejs==17.9.0
+  - pandas=2.1
   - rdkit==2023.09.3
   - recommonmark==0.7.1
   - sphinx==4.5.0
-  - yarn==1.22.19
+  - yarn==1.22.18
   - pip:
     - py3dmol==1.7.0
     - sphinx-rtd-theme==1.0.0

mols2grid/_version.py

@@ -1 +1 @@
-__version__ = "2.0.1-a2"
+__version__ = "2.0.1.dev"

package.json

@@ -1,6 +1,6 @@
 {
   "name": "mols2grid",
-  "version": "2.0.1a2",
+  "version": "2.0.1.dev",
   "description": "Custom widget for the Python mols2grid package",
   "keywords": [
     "jupyter",

pyproject.toml

@@ -38,7 +38,7 @@ dependencies = [
     "ipywidgets>=7.6.0,<9",
     "jinja2>=2.11.0",
     "numpy",
-    "pandas",
+    "pandas"
 ]
 dynamic = ["version"]
 

tests/environment.yml

@@ -6,7 +6,5 @@ dependencies:
   - nodejs==17.9.0
   - yarn==1.22.18
   - pandas
-  - jinja2>=2.11.0
-  - jupyterlab
-  - ipywidgets>=7,<8
+  - jinja2>=3.1.2
   - pytest==6.2.5

tests/notebooks/README.md

@@ -0,0 +1 @@
+See the [ipywidgets dev guide](https://github.com/jupyter-widgets/ipywidgets/blob/main/docs/source/dev_testing.md#visual-regression-tests) for more info.

tests/notebooks/jupyter_server_config.py

@@ -0,0 +1,35 @@
+try:
+    from jupyterlab.galata import configure_jupyter_server
+
+    configure_jupyter_server(c)
+except (ImportError, ModuleNotFoundError):
+    # see https://github.com/jupyterlab/jupyterlab/blob/main/jupyterlab/galata/__init__.py
+    import getpass
+    import os
+    from pathlib import Path
+    from tempfile import mkdtemp
+
+    import jupyterlab
+
+    # Test if we are running in a docker
+    if getpass.getuser() == "jovyan":
+        c.ServerApp.ip = "0.0.0.0"  # noqa S104
+
+    c.ServerApp.port = 8888
+    c.ServerApp.port_retries = 0
+    c.ServerApp.open_browser = False
+    # Add test helpers extension shipped with JupyterLab
+    c.LabServerApp.extra_labextensions_path = str(
+        Path(jupyterlab.__file__).parent / "galata"
+    )
+
+    c.ServerApp.root_dir = os.environ.get(
+        "JUPYTERLAB_GALATA_ROOT_DIR", mkdtemp(prefix="galata-test-")
+    )
+    c.ServerApp.token = ""
+    c.ServerApp.password = ""
+    c.ServerApp.disable_check_xsrf = True
+    c.LabApp.expose_app_in_browser = True
+
+# Uncomment to set server log level to debug level
+# c.ServerApp.log_level = "DEBUG"

tests/notebooks/package.json

@@ -0,0 +1,22 @@
+{
+    "name": "@mols2grid/ui-tests",
+    "private": true,
+    "version": "0.1.0",
+    "description": "mols2grid UI Tests",
+    "scripts": {
+      "start": "jupyter lab --config ./jupyter_server_config.py",
+      "start:detached": "jlpm start&",
+      "test": "npx playwright test",
+      "test:debug": "PWDEBUG=1 npx playwright test",
+      "test:report": "http-server ./playwright-report -a localhost -o",
+      "test:update": "npx playwright test --update-snapshots",
+      "deduplicate": "jlpm && yarn-deduplicate -s fewer --fail"
+    },
+    "author": "Cédric Bouysset",
+    "license": "BSD-3-Clause",
+    "devDependencies": {
+      "@jupyterlab/galata": "^5.0.1",
+      "@playwright/test": "^1.32.0",
+      "yarn-deduplicate": "^6.0.1"
+    }
+  }