Run notebooks in Jupyter Lite as part of ci (Emscripten xeus-cpp automated testing)

.github/actions/Emscripten-Notebook-Tests/action.yml

@@ -0,0 +1,42 @@
+name: 'Run kernel in notebook within Jupyter Lite'
+description: 'This action runs the chosen kernel in notebook within Jupyter Lite'
+
+inputs:
+  notebook:
+    description: "The notebook to run the kernel in"
+    required: true
+    type: string
+  kernel:
+    description: "The kernel to use"
+    required: true
+    type: string
+
+runs:
+  using: composite
+  steps:
+    - name: Jupyter Lite integration test
+      shell: bash -l {0}
+      run: |
+        set -e
+        micromamba activate xeus-lite-host
+        export INPUT_TEXT="" 
+        if [[ "${{ inputs.notebook }}" == "xeus-cpp-lite-demo.ipynb"* ]]; then
+          export INPUT_TEXT="--stdin Smudge"
+        fi 
+        echo "Running xeus-cpp in Jupter Lite in Chrome"
+        python -u scripts/automated-notebook-run-script.py --driver chrome --notebook ${{ inputs.notebook }} --kernel ${{ inputs.kernel }} $INPUT_TEXT
+        nbdiff notebooks/${{ inputs.notebook }} $HOME/Downloads/${{ inputs.notebook }} --ignore-id --ignore-metadata >> chrome_diff.txt
+        export CHROME_TESTS_RETURN_VALUE=$( [ -s chrome_diff.txt ] && echo 1 || echo 0 )
+        rm $HOME/Downloads/${{ inputs.notebook }}   
+        echo "Running xeus-cpp in Jupter Lite in Firefox"
+        python -u scripts/automated-notebook-run-script.py --driver firefox --notebook ${{ inputs.notebook }} --kernel ${{ inputs.kernel }} $INPUT_TEXT
+        nbdiff notebooks/${{ inputs.notebook }} $HOME/Downloads/${{ inputs.notebook }} --ignore-id --ignore-metadata >> firefox_diff.txt
+        export FIREFOX_TESTS_RETURN_VALUE=$( [ -s firefox_diff.txt ] && echo 1 || echo 0 )
+        rm $HOME/Downloads/${{ inputs.notebook }}      
+        if [[ $FIREFOX_TESTS_RETURN_VALUE -ne 0 || $CHROME_TESTS_RETURN_VALUE -ne 0 ]]; then
+          echo "Diff Firefox (blank means no diff)"
+          cat firefox_diff.txt
+          echo "Diff Chrome (blank means no diff)"
+          cat chrome_diff.txt
+          exit 1
+        fi

.github/actions/Jupyter-serve/action.yml

@@ -0,0 +1,34 @@
+name: 'This sets up our Jupyter Lite website, so we can run xeus-cpp in it'
+description: 'This action sets up our Jupyter Lite website, so we can run xeus-cpp in it'
+
+runs:
+  using: composite
+  steps:
+    - name: Jupyter Lite integration test
+      shell: bash -l {0}
+      run: |
+        set -e
+        micromamba create -n xeus-lite-host jupyter_server jupyterlite-xeus -c conda-forge
+        micromamba activate xeus-lite-host
+        if [[ "${{ matrix.os }}" == "macos"* ]]; then
+          brew install coreutils
+          export PATH="$HOMEBREW_PREFIX/opt/coreutils/libexec/gnubin:$PATH"
+        fi
+        timeout 1800 jupyter lite serve --settings-overrides=overrides.json \
+              --XeusAddon.prefix=${{ env.PREFIX }} \
+              --XeusAddon.mounts="${{ env.PREFIX }}/share/xeus-cpp/tagfiles:/share/xeus-cpp/tagfiles" \
+              --XeusAddon.mounts="${{ env.PREFIX }}/etc/xeus-cpp/tags.d:/etc/xeus-cpp/tags.d" \
+              --contents README.md \
+              --contents notebooks/xeus-cpp-lite-demo.ipynb \
+              --contents notebooks/tinyraytracer.ipynb \
+              --contents notebooks/images/marie.png \
+              --contents notebooks/audio/audio.wav \
+              --output-dir dist &
+        # There is a bug in nbdime after 3.2.0 where it will show the filenames as if there was a diff
+        # but there is no diff with the options chosen below (the latest doesn't show a diff, just the filenames with +++
+        # and --- as if it was planning to show a diff.
+        python -m pip install nbdime==3.2.0 selenium
+        # This sleep is to force enough time for the jupyter site to build before trying
+        # to run notebooks in it. If you try to run the notebooks before the website is
+        # ready the ci python script will crash saying ti cannot access the url
+        sleep 10

.github/workflows/deploy-github-page.yml

@@ -137,21 +137,50 @@ jobs:
           fi
         timeout-minutes: 4
 
-      - name: Jupyter Lite integration
-        shell: bash -l {0}
-        run: |
-          micromamba create -n xeus-lite-host jupyter_server jupyterlite-xeus -c conda-forge
-          micromamba activate xeus-lite-host
-          jupyter lite build \
-              --XeusAddon.prefix=${{ env.PREFIX }} \
-              --XeusAddon.mounts="${{ env.PREFIX }}/share/xeus-cpp/tagfiles:/share/xeus-cpp/tagfiles" \
-              --XeusAddon.mounts="${{ env.PREFIX }}/etc/xeus-cpp/tags.d:/etc/xeus-cpp/tags.d" \
-              --contents README.md \
-              --contents notebooks/xeus-cpp-lite-demo.ipynb \
-              --contents notebooks/tinyraytracer.ipynb \
-              --contents notebooks/images/marie.png \
-              --contents notebooks/audio/audio.wav \
-              --output-dir dist
+      - name: Serve Jupyter Lite website
+        uses: ./.github/actions/Jupyter-serve
+
+      - name: Test C++17 kernel in xeus-cpp-lite-demo.ipynb
+        uses: ./.github/actions/Emscripten-Notebook-Tests
+        with:
+          notebook: "xeus-cpp-lite-demo.ipynb"
+          kernel: "C++17"
+        timeout-minutes: 5
+
+      - name: Test C++20 kernel in xeus-cpp-lite-demo.ipynb
+        uses: ./.github/actions/Emscripten-Notebook-Tests
+        with:
+          notebook: "xeus-cpp-lite-demo.ipynb"
+          kernel: "C++20"
+        timeout-minutes: 5
+
+      - name: Test C++23 kernel in xeus-cpp-lite-demo.ipynb
+        uses: ./.github/actions/Emscripten-Notebook-Tests
+        with:
+          notebook: "xeus-cpp-lite-demo.ipynb"
+          kernel: "C++23"
+        timeout-minutes: 5
+
+      - name: Test C++17 kernel in tinyraytracer.ipynb
+        uses: ./.github/actions/Emscripten-Notebook-Tests
+        with:
+          notebook: "tinyraytracer.ipynb"
+          kernel: "C++17"
+        timeout-minutes: 5
+
+      - name: Test C++20 kernel in tinyraytracer.ipynb
+        uses: ./.github/actions/Emscripten-Notebook-Tests
+        with:
+          notebook: "tinyraytracer.ipynb"
+          kernel: "C++20"
+        timeout-minutes: 5
+
+      - name: Test C++23 kernel in tinyraytracer.ipynb
+        uses: ./.github/actions/Emscripten-Notebook-Tests
+        with:
+          notebook: "tinyraytracer.ipynb"
+          kernel: "C++23"
+        timeout-minutes: 5
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v4

.github/workflows/main.yml

@@ -384,12 +384,50 @@ jobs:
           fi
         timeout-minutes: 4
 
-      - name: Jupyter Lite integration
-        shell: bash -l {0}
-        run: |
-          micromamba create -n xeus-lite-host jupyterlite-xeus -c conda-forge
-          micromamba activate xeus-lite-host
-          jupyter lite build --XeusAddon.prefix=${{ env.PREFIX }}
+      - name: Serve Jupyter Lite website
+        uses: ./.github/actions/Jupyter-serve
+
+      - name: Test C++17 kernel in xeus-cpp-lite-demo.ipynb
+        uses: ./.github/actions/Emscripten-Notebook-Tests
+        with:
+          notebook: "xeus-cpp-lite-demo.ipynb"
+          kernel: "C++17"
+        timeout-minutes: 5
+
+      - name: Test C++20 kernel in xeus-cpp-lite-demo.ipynb
+        uses: ./.github/actions/Emscripten-Notebook-Tests
+        with:
+          notebook: "xeus-cpp-lite-demo.ipynb"
+          kernel: "C++20"
+        timeout-minutes: 5
+
+      - name: Test C++23 kernel in xeus-cpp-lite-demo.ipynb
+        uses: ./.github/actions/Emscripten-Notebook-Tests
+        with:
+          notebook: "xeus-cpp-lite-demo.ipynb"
+          kernel: "C++23"
+        timeout-minutes: 5
+
+      - name: Test C++17 kernel in tinyraytracer.ipynb
+        uses: ./.github/actions/Emscripten-Notebook-Tests
+        with:
+          notebook: "tinyraytracer.ipynb"
+          kernel: "C++17"
+        timeout-minutes: 5
+
+      - name: Test C++20 kernel in tinyraytracer.ipynb
+        uses: ./.github/actions/Emscripten-Notebook-Tests
+        with:
+          notebook: "tinyraytracer.ipynb"
+          kernel: "C++20"
+        timeout-minutes: 5
+
+      - name: Test C++23 kernel in tinyraytracer.ipynb
+        uses: ./.github/actions/Emscripten-Notebook-Tests
+        with:
+          notebook: "tinyraytracer.ipynb"
+          kernel: "C++23"
+        timeout-minutes: 5
 
       - name: Setup tmate session
         if: ${{ failure() && runner.debug }}

CONTRIBUTING.md

@@ -164,4 +164,43 @@ jupyter lite serve --XeusAddon.prefix=$PREFIX \
                    --contents notebooks/tinyraytracer.ipynb \
                    --contents notebooks/images/marie.png \
                    --contents notebooks/audio/audio.wav
+
+### xeus-cpp Jupyter Lite tests
+
+It is possible to run test the xeus-cpp in Jupyter Lite deployment, using a Selenium based script and the nbdiff Jupyter tool.
+In order to install these dependencies execute the following (you will need the Jupyter Lite website running in the background when
+executing the python script)
+
+```bash
+python -m pip install nbdime==3.2.0 selenium
+```
+
+Then to run the by executing (--run-browser-gui option exists if you want Chrome or Firefox to show a gui browser as they run)
+
+```bash
+python -u scripts/automated-notebook-run-script.py --driver browser --notebook notebook --kernel kernel --stdin Test_Input --timeout timeout
+```
+
+For example
+
+```bash
+python -u scripts/automated-notebook-run-script.py --driver chrome --notebook xeus-cpp-lite-demo.ipynb  --kernel C++20 --stdin Smudge --timeout 200
+```
+
+will run the xeus-cpp-lite-demo.ipynb notebook in chrome, with the C++20 kernel, enter Test_Name in the standard input box in this notebook,
+and stop the script, if the notebook has finished running after 200 seconds. This works for Safari, Chrome and Firefox. It should be noted
+that in the case of Safari, safari driver  must be enabled, and downloads must be enabled from 127.0.0.1 . Once the script has finished
+executing you can compare the notebook download from the one in the repo, to check the deployment works as expected, by executing
+(replace notebook_run with the notebook chosen for the Python script)
+
+```bash
+nbdiff notebook_run $HOME/Downlaods/notebook_run --ignore-id --ignore-metadata
+```
+
+For example after running the above test command, to test no changes have occurred, execute
+
+```bash
+nbdiff xeus-cpp-lite-demo.ipynb $HOME/Downlaods/xeus-cpp-lite-demo.ipynb --ignore-id --ignore-metadata
+```
+
 ```

README.md

@@ -181,6 +181,44 @@ jupyter lite serve --XeusAddon.prefix=$PREFIX \
                    --contents notebooks/audio/audio.wav
 ```
 
+### xeus-cpp Jupyter Lite tests
+
+It is possible to run test the xeus-cpp in Jupyter Lite deployment, using a Selenium based script and the nbdiff Jupyter tool.
+In order to install these dependencies execute the following (you will need the Jupyter Lite website running in the background when
+executing the python script)
+
+```bash
+python -m pip install nbdime==3.2.0 selenium
+```
+
+Then to run the by executing (--run-browser-gui option exists if you want Chrome or Firefox to show a gui browser as they run)
+
+```bash
+python -u scripts/automated-notebook-run-script.py --driver browser --notebook notebook --kernel kernel --stdin Test_Input --timeout timeout
+```
+
+For example
+
+```bash
+python -u scripts/automated-notebook-run-script.py --driver chrome --notebook xeus-cpp-lite-demo.ipynb  --kernel C++20 --stdin Smudge --timeout 200
+```
+
+will run the xeus-cpp-lite-demo.ipynb notebook in chrome, with the C++20 kernel, enter Test_Name in the standard input box in this notebook,
+and stop the script, if the notebook has finished running after 200 seconds. This works for Safari, Chrome and Firefox. It should be noted
+that in the case of Safari, safari driver  must be enabled, and downloads must be enabled from 127.0.0.1 . Once the script has finished
+executing you can compare the notebook download from the one in the repo, to check the deployment works as expected, by executing
+(replace notebook_run with the notebook chosen for the Python script)
+
+```bash
+nbdiff notebook_run $HOME/Downlaods/notebook_run --ignore-id --ignore-metadata
+```
+
+For example after running the above test command, to test no changes have occurred, execute
+
+```bash
+nbdiff xeus-cpp-lite-demo.ipynb $HOME/Downlaods/xeus-cpp-lite-demo.ipynb --ignore-id --ignore-metadata
+```
+
 ## Trying it online
 
 To try out xeus-cpp interactively in your web browser, just click on the binder link:

docs/source/InstallationAndUsage.rst

@@ -162,6 +162,46 @@ To build and test Jupyter Lite with this kernel locally you can execute the foll
                        --contents notebooks/images/marie.png \
                        --contents notebooks/audio/audio.wav
 
+xeus-cpp Jupyter Lite tests
+========================
+
+It is possible to run test the xeus-cpp in Jupyter Lite deployment, using a Selenium based script and the nbdiff Jupyter tool.
+In order to install these dependencies execute the following (you will need the Jupyter Lite website running in the background when
+executing the python script)
+
+.. code-block:: bash
+
+    python -m pip install nbdime==3.2.0 selenium
+
+Then to run the by executing (--run-browser-gui option exists if you want Chrome or Firefox to show a gui browser as they run)
+
+.. code-block:: bash
+
+    python -u scripts/automated-notebook-run-script.py --driver browser --notebook notebook --kernel kernel --stdin Test_Input --timeout timeout
+
+For example
+
+.. code-block:: bash
+
+    python -u scripts/automated-notebook-run-script.py --driver chrome --notebook xeus-cpp-lite-demo.ipynb  --kernel C++20 --stdin Smudge --timeout 200
+
+will run the xeus-cpp-lite-demo.ipynb notebook in chrome, with the C++20 kernel, enter Test_Name in the standard input box in this notebook,
+and stop the script, if the notebook has finished running after 200 seconds. This works for Safari, Chrome and Firefox. It should be noted
+that in the case of Safari, safari driver  must be enabled, and downloads must be enabled from 127.0.0.1 . Once the script has finished
+executing you can compare the notebook download from the one in the repo, to check the deployment works as expected, by executing
+(replace notebook_run with the notebook chosen for the Python script)
+
+.. code-block:: bash
+
+    nbdiff notebook_run $HOME/Downlaods/notebook_run --ignore-id --ignore-metadata
+
+
+For example after running the above test command, to test no changes have occurred, execute
+
+.. code-block:: bash
+
+    nbdiff xeus-cpp-lite-demo.ipynb $HOME/Downlaods/xeus-cpp-lite-demo.ipynb --ignore-id --ignore-metadata
+
 Installing from conda-forge
 ===========================
 

docs/source/conf.py

@@ -38,7 +38,8 @@
 cd {XEUS_CPP_ROOT};
 micromamba create -n xeus-lite-host jupyter_server jupyterlite-xeus -c conda-forge -y;
 micromamba activate xeus-lite-host;
-jupyter lite build --XeusAddon.prefix=$PREFIX \\
+jupyter lite build --settings-overrides=overrides.json \\
+                   --XeusAddon.prefix=$PREFIX \\
                    --XeusAddon.mounts="$PREFIX/share/xeus-cpp/tagfiles:/share/xeus-cpp/tagfiles" \
                    --XeusAddon.mounts="$PREFIX/etc/xeus-cpp/tags.d:/etc/xeus-cpp/tags.d" \
                    --contents notebooks/xeus-cpp-lite-demo.ipynb \\

notebooks/xeus-cpp-lite-demo.ipynb

@@ -287,7 +287,7 @@
         {
           "output_type": "display_data",
           "data": {
-            "text/html": "<style>\n            #pager-container {\n                padding: 0;\n                margin: 0;\n                width: 100%;\n                height: 100%;\n            }\n            .xcpp-iframe-pager {\n                padding: 0;\n                margin: 0;\n                width: 100%;\n                height: 100%;\n                border: none;\n            }\n            </style>\n            <iframe class=\"xcpp-iframe-pager\" src=\"https://en.cppreference.com/w/cpp/container/vector?action=purge\"></iframe>",
+            "text/html": "<style>\n        #pager-container {\n            padding: 0;\n            margin: 0;\n            width: 100%;\n            height: 100%;\n        }\n        .xcpp-iframe-pager {\n            padding: 0;\n            margin: 0;\n            width: 100%;\n            height: 100%;\n            border: none;\n        }\n        </style>\n        <iframe class=\"xcpp-iframe-pager\" src=\"https://en.cppreference.com/w/cpp/container/vector?action=purge\"></iframe>",
             "text/plain": "https://en.cppreference.com/w/cpp/container/vector"
           },
           "metadata": {}
@@ -585,8 +585,14 @@
       "metadata": {
         "trusted": true
       },
-      "outputs": [],
-      "execution_count": null
+      "outputs": [
+        {
+          "output_type": "stream",
+          "name": "stdin",
+          "text": " Smudge\n"
+        }
+      ],
+      "execution_count": 29
     },
     {
       "id": "8ec65830-4cb5-4d01-a860-f6c46ac4f60f",
@@ -595,8 +601,24 @@
       "metadata": {
         "trusted": true
       },
+      "outputs": [
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": "Your name is Smudge"
+        }
+      ],
+      "execution_count": 30
+    },
+    {
+      "id": "e4ad61d7-092c-49f6-98a7-6449fd74d731",
+      "cell_type": "code",
+      "source": "",
+      "metadata": {
+        "trusted": true
+      },
       "outputs": [],
       "execution_count": null
     }
   ]
-}
+}