Gather more python and JS coverage (#124)

.github/workflows/ci.yml

@@ -7,12 +7,17 @@ on:
     branches: [master]
   workflow_dispatch:
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 env:
   PYTHONIOENCODING: utf-8
   PYTHONUNBUFFERED: '1'
   PIP_DISABLE_PIP_VERSION_CHECK: '1'
   CACHE_EPOCH: 6
   ATEST_RETRIES: 2
+  ALL_PY_COV_FAIL_UNDER: 69
 
 jobs:
   build:
@@ -21,7 +26,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: prefix-dev/[email protected]
         with:
-          pixi-version: v0.32.1
+          pixi-version: v0.34.0
           cache: true
           environments: build
           cache-key: job-build
@@ -47,7 +52,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: prefix-dev/[email protected]
         with:
-          pixi-version: v0.32.1
+          pixi-version: v0.34.0
           cache: true
           environments: build lint
           cache-key: job-lint
@@ -69,7 +74,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: prefix-dev/[email protected]
         with:
-          pixi-version: v0.32.1
+          pixi-version: v0.34.0
           cache: true
           environments: build check docs lite
           cache-key: job-lint
@@ -103,14 +108,26 @@ jobs:
         exclude:
           - { vm: macos-13, task: test }
           - { vm: macos-latest, task: test-oldest }
+        include:
+          - { vm: macos-13, atest-args: '' }
+          - { vm: macos-latest, atest-args: '' }
+          - { vm: ubuntu-latest, atest-args: '' }
+          - { vm: windows-latest, atest-args: '--exclude ci:skip-win' }
+    env:
+      ATEST_ARGS: ${{ matrix.atest-args }}
     steps:
       - uses: actions/checkout@v4
       - uses: prefix-dev/[email protected]
         with:
-          pixi-version: v0.32.1
+          pixi-version: v0.34.0
           cache: true
           environments: a${{ matrix.task }} i${{ matrix.task }} u${{ matrix.task }}
           cache-key: job-${{ matrix.task }}
+      - if: matrix.task == 'test'
+        uses: actions/cache@v4
+        with:
+          path: node_modules
+          key: ${{ env.CACHE_EPOCH }}-${{ hashFiles('yarn.lock') }}-node-modules
       - uses: actions/download-artifact@v4
         with:
           name: ipyelk-${{ github.run_number }}-dist

.readthedocs.yml

@@ -11,6 +11,7 @@ build:
       - pixi install --environment=docs
       - pixi run setup-js
       - pixi run build
+      - pixi run dist
       - pixi run docs-lite
 
 conda:

CONTRIBUTING.md

@@ -6,7 +6,7 @@
 - Get [pixi](https://pixi.sh)
 
 ```bash
-mamba install pixi
+mamba install "pixi==0.34.0"
 ```
 
 ## Get Started
@@ -87,6 +87,7 @@ _Log Console_, opened with the _Show Log Console_ command.
 ```bash
 pixi run fix
 pixi run lint
+pixi run test
 ```
 
 - Ensure the `examples/` work. These will be tested in CI with:
@@ -97,8 +98,12 @@ pixi run lint
     - Treat each feature as a function which can be reused for other examples, with:
       - the example in a humane name, e.g. `a_basic_elk_example`
       - some suitable defaults and knobs to twiddle
-  - Add appropriate links to your new example.
-  - Add appropriate Robot Framework tests
+    - Add appropriate links to your new example.
+    - These will be picked up by `itest`
+  - Potentially add some unit `./tests`
+  - Add appropriate Robot Framework in `./atest`
+- Ensure coverage doesn't degrade from the `ALL_PY_COV_FAIL_UNDER` baseline in
+  `.github/ci.yml`
 
 ### Limiting Testing
 

README.md

@@ -18,7 +18,7 @@
 
 ## Prerequisites
 
-- `python >=3.11`
+- `python >=3.9`
 
 ### JupyterLab compatibility
 
@@ -36,15 +36,15 @@
 ### `ipyelk` with `conda` (recommended)
 
 ```bash
-conda install -c conda-forge ipyelk jupyterlab=4
+conda install -c conda-forge ipyelk "jupyterlab=4.*"
+# or
+mamba install -c conda-forge ipyelk "jupyterlab=4.*"
 ```
 
 ### `ipyelk` with `pip`
 
-install `nodejs` with a [package manager][package-manager]
-
 ```bash
-pip install ipyelk jupyterlab=4
+pip install ipyelk "jupyterlab=4.*"
 ```
 
 ### Developing

atest/Notebooks/02_Transformer.robot

@@ -13,7 +13,7 @@ ${SCREENS}      ${SCREENS ROOT}${/}examples${/}02_Transformer
 
 *** Test Cases ***
 02_Transformer
-    [Tags]    data:flat_graph.json    data:hier_tree.json    data:hier_ports.json
+    [Tags]    data:flat_graph.json    data:hier_tree.json    data:hier_ports.json    ci:skip-win
     Example Should Restart-and-Run-All    ${TRANSFORMER}
     Click Elk Tool    Center    1
     Scroll To Notebook Cell    10

atest/_resources/keywords/Coverage.robot

@@ -0,0 +1,28 @@
+*** Settings ***
+Documentation       Keywords for working with browser coverage data
+
+Library             OperatingSystem
+Library             SeleniumLibrary
+Library             uuid
+
+
+*** Keywords ***
+Get Next Coverage File
+    [Documentation]    Get a random filename.
+    ${uuid} =    UUID1
+    RETURN    ${uuid.__str__()}
+
+Capture Page Coverage
+    [Documentation]    Fetch coverage data from the browser.
+    [Arguments]    ${name}=${EMPTY}
+    IF    not '''${name}'''
+        ${name} =    Get Next Coverage File
+    END
+    ${cov_json} =    Execute Javascript
+    ...    return window.__coverage__ && JSON.stringify(window.__coverage__, null, 2)
+    IF    ${cov_json}
+        Create File    ${OUTPUT DIR}${/}jscov${/}${name}.json    ${cov_json}
+        Execute Javascript    window.__coverage__ = {}
+    ELSE
+        Log    No browser coverage captured    ERROR
+    END

atest/_resources/keywords/Lab.robot

@@ -2,6 +2,7 @@
 Library     OperatingSystem
 Library     SeleniumLibrary
 Resource    Browser.robot
+Resource    Coverage.robot
 Resource    ../variables/Lab.robot
 Resource    ../variables/Browser.robot
 
@@ -141,6 +142,7 @@ Open ${file} in ${editor}
 
 Clean Up After Working With Files
     [Arguments]    @{files}
+    IF    ${TOTAL_COVERAGE}    Capture Page Coverage
     FOR    ${file}    IN    @{files}
         ${src}    ${name} =    Split Path    ${file}
         Remove File    ${OUTPUT DIR}${/}home${/}${name}
@@ -203,9 +205,6 @@ Get Editor Content
     ${content} =    Execute JavaScript    return document.querySelector('${css} .CodeMirror').CodeMirror.getValue()
     RETURN    ${content}
 
-Close JupyterLab
-    Close All Browsers
-
 Open Command Palette
     Press Keys    id:main    ${ACCEL}+SHIFT+c
     Wait Until Element Is Visible    ${CMD PALETTE INPUT}

atest/_resources/keywords/Server.robot

@@ -4,8 +4,25 @@ Library     Process
 Library     String
 Resource    Lab.robot
 Resource    Browser.robot
+Resource    Coverage.robot
 Resource    ../variables/Server.robot
 Library     ../../_libraries/Ports.py
+Library     json
+
+
+*** Variables ***
+${JUPYTERLAB_EXE}           jupyter-lab
+${TOTAL_COVERAGE}           0
+${CALLER_ID}                0000
+${PABOTQUEUEINDEX}          0
+${PABOTEXECUTIONPOOLID}     0
+
+# paths relative to home
+${DOT_LOCAL_PATH}           .local
+${ETC_PATH}                 ${DOT_LOCAL_PATH}${/}etc${/}jupyter
+${SHARE_PATH}               ${DOT_LOCAL_PATH}${/}share${/}jupyter
+${KERNELS_PATH}             ${SHARE_PATH}${/}kernels
+${USER_SETTINGS_PATH}       ${ETC_PATH}${/}lab${/}user-settings
 
 
 *** Keywords ***
@@ -23,12 +40,18 @@ Setup Server and Browser
     Create Directory    ${OUTPUT DIR}${/}logs
     Create Notebok Server Config    ${home}
     Initialize User Settings
+    IF    "${TOTAL_COVERAGE}" == "1"    Initialize Coverage Kernel    ${home}
     ${cmd} =    Create Lab Launch Command    ${root}
     Set Screenshot Directory    ${SCREENS ROOT}
     Set Global Variable    ${NEXT LAB}    ${NEXT LAB.__add__(1)}
     Set Global Variable    ${LAB LOG}    ${OUTPUT DIR}${/}logs${/}lab-${NEXT LAB}.log
     Set Global Variable    ${PREVIOUS LAB LOG LENGTH}    0
-    ${server} =    Start Process    ${cmd}    shell=yes    env:HOME=${home}    cwd=${home}    stdout=${LAB LOG}
+    ${server} =    Start Process    ${cmd}    shell=yes
+    ...    env:HOME=${home}
+    ...    env:JUPYTER_CONFIG_DIR=${home}${/}${ETC_PATH}
+    ...    env:JUPYTER_PREFER_ENV_PATH=0
+    ...    cwd=${home}
+    ...    stdout=${LAB LOG}
     ...    stderr=STDOUT
     Set Global Variable    ${SERVER}    ${server}
     Wait For Jupyter Server To Be Ready
@@ -39,6 +62,36 @@ Setup Server and Browser
     Set Global Variable    ${LAB VERSION}    ${config["appVersion"]}
     Set Tags    lab:${LAB VERSION}
 
+Initialize Coverage Kernel
+    [Documentation]    Copy and patch the env kernel to run under coverage.
+    [Arguments]    ${home_dir}
+    ${kernels_dir} =    Set Variable    ${home_dir}${/}${KERNELS_PATH}
+    Create Directory    ${kernels_dir}
+    ${spec_dir} =    Set Variable    ${kernels_dir}${/}python3
+    Copy Directory    %{CONDA_PREFIX}${/}share${/}jupyter${/}kernels${/}python3    ${spec_dir}
+    ${spec_path} =    Set Variable    ${spec_dir}${/}kernel.json
+    ${spec_text} =    Get File    ${spec_path}
+    ${spec_json} =    Loads    ${spec_text}
+    ${cov_path} =    Set Variable    ${OUTPUT_DIR}${/}pycov
+    Create Directory    ${cov_path}
+    ${rest} =    Get Slice From List    ${spec_json["argv"]}    1
+    ${argv} =    Create List
+    ...    ${spec_json["argv"][0]}
+    ...    -m
+    ...    coverage    run
+    ...    --parallel-mode
+    ...    --branch
+    ...    --source    ipyelk
+    ...    --context    atest-${PABOTQUEUEINDEX}-${PABOTEXECUTIONPOOLID}-${CALLER_ID}
+    ...    --concurrency    thread
+    ...    --data-file    ${cov_path}${/}.coverage
+    ...    @{rest}
+    Set To Dictionary    ${spec_json}    argv=${argv}
+    ${spec_text} =    Dumps    ${spec_json}    indent=${2}    sort_keys=${TRUE}
+    Log    ${spec_text}
+    Create File    ${spec_path}    ${spec_text}
+    RETURN    ${spec_path}
+
 Create Lab Launch Command
     [Documentation]    Create a JupyterLab CLI shell string, escaping for traitlets
     [Arguments]    ${root}

docs/conf.py

@@ -2,12 +2,15 @@
 
 # Copyright (c) 2024 ipyelk contributors.
 # Distributed under the terms of the Modified BSD License.
+from __future__ import annotations
+
 import os
 import subprocess
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
+    from docutils import nodes
     from sphinx.application import Sphinx
 
 # our project data
@@ -20,8 +23,8 @@
     # provide a fake root doc
     root_doc = "rtd"
 
-    def setup(app: "Sphinx") -> None:
-        """Customize the sphinx build lifecycle."""
+    def setup(app: Sphinx) -> None:
+        """Customize the sphinx build lifecycle in the outer RTD environment."""
 
         def _run_pixi(*_args: Any) -> None:
             args = ["pixi", "run", "-v", "docs-rtd"]
@@ -31,10 +34,8 @@ def _run_pixi(*_args: Any) -> None:
         app.connect("build-finished", _run_pixi)
 
 else:
-    try:
-        import tomllib
-    except Exception:
-        import tomli as tomllib
+    import pypandoc
+    import tomllib
 
     PY_PROJ = tomllib.loads((ROOT / "pyproject.toml").read_text(encoding="utf-8"))
     PROJ = PY_PROJ["project"]
@@ -46,6 +47,7 @@ def _run_pixi(*_args: Any) -> None:
         "sphinx.ext.autosummary",
         "sphinx.ext.autodoc",
         "sphinx_autodoc_typehints",
+        "sphinx-jsonschema",
     ]
 
     # meta
@@ -83,3 +85,31 @@ def _run_pixi(*_args: Any) -> None:
         "doc_path": "docs",
     }
     html_static_path = ["_static", "../build/lite"]
+
+    jsonschema_options = {
+        "auto_reference": True,
+        "lift_definitions": True,
+        "lift_description": True,
+    }
+
+    def setup(app: Sphinx) -> None:
+        """Customize the sphinx build lifecycle in the inner build environemnt."""
+
+        def _md_description(
+            self, schema: dict[str, Any], container: nodes.Node | list[nodes.Node]
+        ) -> None:
+            """Convert (simple) markdown descriptions to (simple) rst."""
+            description = schema.pop("description", None)
+            if not description:
+                return
+            rst = pypandoc.convert_text(description, "rst", format="md")
+            if isinstance(container, list):
+                container.append(self._linme(self._cell(rst)))
+            else:
+                self.state.nested_parse(
+                    self._convert_content(rst), self.lineno, container
+                )
+
+        wf_cls = __import__("sphinx-jsonschema.wide_format").wide_format.WideFormat
+        wf_cls._get_description = _md_description
+        wf_cls._check_description = _md_description

docs/reference/index.md

@@ -8,4 +8,5 @@ widgets
 tools
 loaders
 pipes
+schema
 ```

docs/reference/schema.rst

@@ -0,0 +1,4 @@
+JSON Schema
+===========
+
+.. jsonschema:: ../../src/ipyelk/schema/elkschema.json

docs/rtd.yml

@@ -2,4 +2,4 @@ channels:
   - conda-forge
   - nodefaults
 dependencies:
-  - pixi ==0.32.1
+  - pixi ==0.34.0

js/display_widget.ts

@@ -1,5 +1,5 @@
 /**
- * # Copyright (c) 2024 ipyelk contributors.
+ * Copyright (c) 2024 ipyelk contributors.
  * Distributed under the terms of the Modified BSD License.
  */
 import difference from 'lodash/difference';

js/exporter.ts

@@ -1,5 +1,5 @@
 /**
- * # Copyright (c) 2024 ipyelk contributors.
+ * Copyright (c) 2024 ipyelk contributors.
  * Distributed under the terms of the Modified BSD License.
  */
 import { WidgetModel, WidgetView } from '@jupyter-widgets/base';