Emscripten notebook tests

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

@@ -0,0 +1,55 @@
+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 }}      
+        export SAFARI_TESTS_RETURN_VALUE=0
+        touch safari_diff.txt
+        if [[ "${{ matrix.os }}" == "macos"* ]]; then
+          echo "Running xeus-cpp in Jupter Lite in  Safari"
+          python -u scripts/automated-notebook-run-script.py --driver safari --notebook ${{ inputs.notebook }} --kernel ${{ inputs.kernel }} $INPUT_TEXT
+          nbdiff notebooks/${{ inputs.notebook }} $HOME/Downloads/${{ inputs.notebook }} --ignore-id --ignore-metadata >> safari_diff.txt
+          export SAFARI_TESTS_RETURN_VALUE=$( [ -s safari_diff.txt ] && echo 1 || echo 0 )
+          rm $HOME/Downloads/${{ inputs.notebook }}
+        fi
+        if [[ $SAFARI_TESTS_RETURN_VALUE -ne 0 || $FIREFOX_TESTS_RETURN_VALUE -ne 0 || $CHROME_TESTS_RETURN_VALUE -ne 0 ]]; then
+          if [[ "${{ matrix.os }}" == "macos"* ]]; then
+             echo "Diff Safari (blank means no diff)"
+             cat safari_diff.txt
+          fi
+          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,37 @@
+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 jupyterlite-core=0.6 jupyterlite-xeus -c conda-forge -y
+        micromamba activate xeus-lite-host
+        if [[ "${{ matrix.os }}" == "macos"* ]]; then
+          brew install coreutils
+          export PATH="$HOMEBREW_PREFIX/opt/coreutils/libexec/gnubin:$PATH"
+        fi
+        timeout 900 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/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. This only happens for xeus-cpp-lite-demo.ipynb.
+        python -m pip install nbdime==3.2.0
+        if [[ "${{ matrix.os }}" == "macos"* ]]; then
+          python -m pip install PyAutoGUI
+          python scripts/enable-downloads-safari-github-ci.py
+        fi
+        python -m pip install 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 15

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

@@ -139,21 +139,29 @@ jobs:
           fi
         timeout-minutes: 4
 
-      - name: Jupyter Lite integration
-        shell: bash -l {0}
-        run: |
-          micromamba create -n xeus-lite-host jupyterlite-core=0.6 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/smallpt.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: Upload artifact
         uses: actions/upload-pages-artifact@v3

.github/workflows/main.yml

@@ -329,12 +329,29 @@ jobs:
           fi
         timeout-minutes: 4
 
-      - name: Jupyter Lite integration
-        shell: bash -l {0}
-        run: |
-          micromamba create -n xeus-lite-host jupyterlite-core=0.6 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: Setup tmate session
         if: ${{ failure() && runner.debug }}

CMakeLists.txt

@@ -409,14 +409,6 @@ if (XEUS_CPP_BUILD_EXECUTABLE)
 endif()
 
 if(EMSCRIPTEN)
-    # Ensure required SDL2 ports (e.g. SDL2) are built before header preloading
-    execute_process(
-        COMMAND embuilder${EMCC_SUFFIX} build sdl2
-        RESULT_VARIABLE SDL2_RESULT
-    )
-    if(NOT SDL2_RESULT EQUAL 0)
-        message(FATAL_ERROR "Failed to run 'embuilder build sdl2'")
-    endif()
     include(WasmBuildOptions)
     find_package(xeus-lite ${xeus_lite_REQUIRED_VERSION} REQUIRED)
     add_executable(xcpp src/main_emscripten_kernel.cpp )
@@ -429,7 +421,6 @@ if(EMSCRIPTEN)
     string(REPLACE "\\" "/" ESCAPED_XEUS_CPP_RESOURCE_DIR "${ESCAPED_XEUS_CPP_RESOURCE_DIR}")
     string(REPLACE "\\" "/" ESCAPED_SYSROOT_PATH "${ESCAPED_SYSROOT_PATH}")
     target_link_options(xcpp
-        PUBLIC "SHELL: -s USE_SDL=2"
         PUBLIC "SHELL: --preload-file ${ESCAPED_SYSROOT_PATH}/include@/include"
         PUBLIC "SHELL: --preload-file ${ESCAPED_XEUS_CPP_RESOURCE_DIR}@/${CMAKE_INSTALL_LIBDIR}/clang/${CPPINTEROP_LLVM_VERSION_MAJOR}"
         PUBLIC "SHELL: --post-js ${CMAKE_CURRENT_SOURCE_DIR}/wasm_patches/post.js"

CONTRIBUTING.md

@@ -161,7 +161,45 @@ jupyter lite serve --XeusAddon.prefix=$PREFIX \
                    --XeusAddon.mounts="$PREFIX/etc/xeus-cpp/tags.d:/etc/xeus-cpp/tags.d" \
                    --contents README.md \
                    --contents notebooks/xeus-cpp-lite-demo.ipynb \
-                   --contents notebooks/smallpt.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

@@ -71,7 +71,6 @@ cd ../test
 pytest -sv test_xcpp_kernel.py
 ```
 to perform the python tests.
-```
 
 ## Installation within a mamba environment (wasm build instructions)
 
@@ -177,11 +176,48 @@ jupyter lite serve --XeusAddon.prefix=$PREFIX \
                    --XeusAddon.mounts="$PREFIX/etc/xeus-cpp/tags.d:/etc/xeus-cpp/tags.d" \
                    --contents README.md \
                    --contents notebooks/xeus-cpp-lite-demo.ipynb \
-                   --contents notebooks/smallpt.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
+```
+
 ## Trying it online
 
 To try out xeus-cpp interactively in your web browser, just click on the binder link:

docs/source/InstallationAndUsage.rst

@@ -158,10 +158,48 @@ To build and test Jupyter Lite with this kernel locally you can execute the foll
                        --XeusAddon.mounts="$PREFIX/etc/xeus-cpp/tags.d:/etc/xeus-cpp/tags.d" \
                        --contents README.md \
                        --contents notebooks/xeus-cpp-lite-demo.ipynb \
-                       --contents notebooks/smallpt.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)
+
+.. 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

@@ -37,11 +37,10 @@
 micromamba create -n xeus-lite-host jupyterlite-core=0.6 jupyter_server jupyterlite-xeus -c conda-forge -y;
 micromamba activate xeus-lite-host;
 python -m pip install jupyterlite-xeus jupyter_server;
-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 \\
-                   --contents notebooks/smallpt.ipynb \\
                    --contents notebooks/images/marie.png \\
                    --contents notebooks/audio/audio.wav \\
                    --output-dir $READTHEDOCS_OUTPUT/html/xeus-cpp;