compiler-research · mcbarton · May 26, 2025 · May 1, 2025
diff --git a/.github/workflows/deploy-github-page.yml b/.github/workflows/deploy-github-page.yml
@@ -51,6 +51,7 @@ jobs:
           pushd build
 
           export BUILD_PREFIX=$MAMBA_ROOT_PREFIX/envs/xeus-cpp-wasm-build
+          echo "BUILD_PREFIX=$BUILD_PREFIX" >> $GITHUB_ENV
           export PREFIX=$MAMBA_ROOT_PREFIX/envs/xeus-cpp-wasm-host 
           echo "PREFIX=$PREFIX" >> $GITHUB_ENV
           export SYSROOT_PATH=$BUILD_PREFIX/opt/emsdk/upstream/emscripten/cache/sysroot
@@ -65,6 +66,77 @@ jobs:
             ..
           emmake make -j ${{ env.ncpus }} install
 
+      - name: Test xeus-cpp C++ Emscripten
+        shell: bash -l {0}
+        run: |
+          set -e
+          micromamba create -n xeus-lite-host jupyterlite-core
+          micromamba activate xeus-lite-host
+          cd build/test
+          # Fresh install browsers, and run Emscripten tests in them
+          # This is to match the Emscripten build instructions, where
+          # we run in a fresh browser, to stop any extra installed
+          # stuff interferring with the running of the tests
+          # Explaination of options for emrun
+          # --browser (name of browser on path)
+          # --kill_exit makes it so that when emrun finishes,
+          # that the headless browser we create is killed along with it
+          # --timeout 60 is such that emrun is killed after 60 seconds if
+          # still running. emrun should have finished long before then,
+          # so if it is still running, something went wrong (such as a test
+          # which crashed the html file). This will cause the ci to fail,
+          # as a non 0 value of will be returned.
+          # In the case of Chrome we have the extra --no-sandbox flag, as on
+          # Ubuntu Chrome will refuse to run otherwise, as it expects to have
+          # been installed with admin privileges. This flag allows it to run
+          # in userspace.
+          os="${{ matrix.os }}"
+          if [[ "${os}" == "macos"* ]]; then
+            # Install Firefox
+            wget "https://download.mozilla.org/?product=firefox-latest&os=osx&lang=en-US" -O Firefox-latest.dmg
+            hdiutil attach Firefox-latest.dmg
+            cp -r /Volumes/Firefox/Firefox.app $PWD
+            hdiutil detach /Volumes/Firefox
+            cd ./Firefox.app/Contents/MacOS/
+            export PATH="$PWD:$PATH"
+            cd –
+
+            # Install Google Chrome
+            wget https://dl.google.com/chrome/mac/stable/accept_tos%3Dhttps%253A%252F%252Fwww.google.com%252Fintl%252Fen_ph%252Fchrome%252Fterms%252F%26_and_accept_tos%3Dhttps%253A%252F%252Fpolicies.google.com%252Fterms/googlechrome.pkg
+            pkgutil --expand-full googlechrome.pkg google-chrome
+            cd ./google-chrome/GoogleChrome.pkg/Payload/Google\ Chrome.app/Contents/MacOS/
+            export PATH="$PWD:$PATH"
+            cd –
+
+            # Run tests in browsers
+            echo "Running test_xeus_cpp in Firefox"
+            python ${{ env.BUILD_PREFIX }}/bin/emrun.py --browser="firefox" --kill_exit --browser-args="--headless"  test_xeus_cpp.html
+            echo "Running test_xeus_cpp in Google Chrome"
+            python ${{ env.BUILD_PREFIX }}/bin/emrun.py --browser="Google Chrome" --kill_exit --browser-args="--headless"  test_xeus_cpp.html
+          else
+            # Install Google Chrome
+            wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
+            dpkg-deb -x google-chrome-stable_current_amd64.deb $PWD/chrome
+            cd ./chrome/opt/google/chrome/
+            export PATH="$PWD:$PATH"
+            cd -
+
+            # Install Firefox
+            wget https://ftp.mozilla.org/pub/firefox/releases/138.0.1/linux-x86_64/en-GB/firefox-138.0.1.tar.xz
+            tar -xJf firefox-138.0.1.tar.xz
+            cd ./firefox
+            export PATH="$PWD:$PATH"
+            cd -
+
+            # Run tests in browsers
+            echo "Running test_xeus_cpp in Firefox"
+            python ${{ env.BUILD_PREFIX }}/bin/emrun.py --browser="firefox" --kill_exit --timeout 60 --browser-args="--headless"  test_xeus_cpp.html
+            echo "Running test_xeus_cpp in Google Chrome"
+            python ${{ env.BUILD_PREFIX }}/bin/emrun.py --browser="google-chrome" --kill_exit --timeout 60 --browser-args="--headless  --no-sandbox"  test_xeus_cpp.html
+          fi
+          node test_xeus_cpp.js
+        timeout-minutes: 4
+
       - name: Jupyter Lite integration
         shell: bash -l {0}
         run: |

diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -234,6 +234,7 @@ jobs:
           pushd build
 
           export BUILD_PREFIX=$MAMBA_ROOT_PREFIX/envs/xeus-cpp-wasm-build
+          echo "BUILD_PREFIX=$BUILD_PREFIX" >> $GITHUB_ENV
           export PREFIX=$MAMBA_ROOT_PREFIX/envs/xeus-cpp-wasm-host
           echo "PREFIX=$PREFIX" >> $GITHUB_ENV
           export SYSROOT_PATH=$BUILD_PREFIX/opt/emsdk/upstream/emscripten/cache/sysroot
@@ -251,10 +252,72 @@ jobs:
       - name: Test xeus-cpp C++ Emscripten
         shell: bash -l {0}
         run: |
+          export BUILD_PREFIX=$MAMBA_ROOT_PREFIX/envs/xeus-cpp-wasm-build
           set -e
           micromamba create -n xeus-lite-host jupyterlite-core
           micromamba activate xeus-lite-host
           cd build/test
+          # Fresh install browsers, and run Emscripten tests in them
+          # This is to match the Emscripten build instructions, where
+          # we run in a fresh browser, to stop any extra installed
+          # stuff interferring with the running of the tests
+          # Explaination of options for emrun
+          # --browser (name of browser on path)
+          # --kill_exit makes it so that when emrun finishes,
+          # that the headless browser we create is killed along with it
+          # --timeout 60 is such that emrun is killed after 60 seconds if
+          # still running. emrun should have finished long before then,
+          # so if it is still running, something went wrong (such as a test
+          # which crashed the html file). This will cause the ci to fail,
+          # as a non 0 value of will be returned.
+          # In the case of Chrome we have the extra --no-sandbox flag, as on
+          # Ubuntu Chrome will refuse to run otherwise, as it expects to have
+          # been installed with admin privileges. This flag allows it to run
+          # in userspace.
+          os="${{ matrix.os }}"
+          if [[ "${os}" == "macos"* ]]; then
+            # Install Firefox
+            wget "https://download.mozilla.org/?product=firefox-latest&os=osx&lang=en-US" -O Firefox-latest.dmg
+            hdiutil attach Firefox-latest.dmg
+            cp -r /Volumes/Firefox/Firefox.app $PWD
+            hdiutil detach /Volumes/Firefox
+            cd ./Firefox.app/Contents/MacOS/
+            export PATH="$PWD:$PATH"
+            cd -
+
+            # Install Google Chrome
+            wget https://dl.google.com/chrome/mac/stable/accept_tos%3Dhttps%253A%252F%252Fwww.google.com%252Fintl%252Fen_ph%252Fchrome%252Fterms%252F%26_and_accept_tos%3Dhttps%253A%252F%252Fpolicies.google.com%252Fterms/googlechrome.pkg
+            pkgutil --expand-full googlechrome.pkg google-chrome
+            cd ./google-chrome/GoogleChrome.pkg/Payload/Google\ Chrome.app/Contents/MacOS/
+            export PATH="$PWD:$PATH"
+            cd -
+
+            # Run tests in browsers
+            echo "Running test_xeus_cpp in Firefox"
+            python ${{ env.BUILD_PREFIX }}/bin/emrun.py --browser="firefox" --kill_exit --timeout 60 --browser-args="--headless"  test_xeus_cpp.html
+            echo "Running test_xeus_cpp in Google Chrome"
+            python ${{ env.BUILD_PREFIX }}/bin/emrun.py --browser="Google Chrome" --kill_exit --timeout 60 --browser-args="--headless  --no-sandbox"  test_xeus_cpp.html
+          else
+            # Install Google Chrome
+            wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
+            dpkg-deb -x google-chrome-stable_current_amd64.deb $PWD/chrome
+            cd ./chrome/opt/google/chrome/
+            export PATH="$PWD:$PATH"
+            cd -
+
+            # Install Firefox
+            wget https://ftp.mozilla.org/pub/firefox/releases/138.0.1/linux-x86_64/en-GB/firefox-138.0.1.tar.xz
+            tar -xJf firefox-138.0.1.tar.xz
+            cd ./firefox
+            export PATH="$PWD:$PATH"
+            cd -
+
+            # Run tests in browsers
+            echo "Running test_xeus_cpp in Firefox"
+            python ${{ env.BUILD_PREFIX }}/bin/emrun.py --browser="firefox" --kill_exit --timeout 60 --browser-args="--headless"  test_xeus_cpp.html
+            echo "Running test_xeus_cpp in Google Chrome"
+            python ${{ env.BUILD_PREFIX }}/bin/emrun.py --browser="google-chrome" --kill_exit --timeout 60 --browser-args="--headless --no-sandbox"  test_xeus_cpp.html
+          fi
           node test_xeus_cpp.js
         timeout-minutes: 4
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -94,6 +94,57 @@ emcmake cmake \
 emmake make install
 ```
 
+To test the lite build you can execute the following to run the C++ tests built against emscripten in node
+
+```bash
+cd test
+node test_xeus_cpp.js
+```
+
+It is possible to run the Emscripten tests in a headless browser. We will run our tests in a fresh installed browser. Installing the browsers, and running the tests within the installed browsers will be platform dependent. To do this on MacOS execute the following
+
+```bash
+    wget "https://download.mozilla.org/?product=firefox-latest&os=osx&lang=en-US" -O Firefox-latest.dmg
+    hdiutil attach Firefox-latest.dmg
+    cp -r /Volumes/Firefox/Firefox.app $PWD
+    hdiutil detach /Volumes/Firefox
+    cd ./Firefox.app/Contents/MacOS/
+    export PATH="$PWD:$PATH"
+    cd –
+
+    wget https://dl.google.com/chrome/mac/stable/accept_tos%3Dhttps%253A%252F%252Fwww.google.com%252Fintl%252Fen_ph%252Fchrome%252Fterms%252F%26_and_accept_tos%3Dhttps%253A%252F%252Fpolicies.google.com%252Fterms/googlechrome.pkg
+    pkgutil --expand-full googlechrome.pkg google-chrome
+    cd ./google-chrome/GoogleChrome.pkg/Payload/Google\ Chrome.app/Contents/MacOS/
+    export PATH="$PWD:$PATH"
+    cd –
+
+    echo "Running test_xeus_cpp in Firefox"
+    python $BUILD_PREFIX/bin/emrun.py --browser="firefox" --kill_exit --browser-args="--headless"  test_xeus_cpp.html
+    echo "Running test_xeus_cpp in Google Chrome"
+    python $BUILD_PREFIX/bin/emrun.py --browser="Google Chrome" --kill_exit --browser-args="--headless  --no-sandbox"  test_xeus_cpp.html
+```
+
+To do this on Ubuntu x86 execute the following
+
+```bash
+    wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
+    dpkg-deb -x google-chrome-stable_current_amd64.deb $PWD/chrome
+    cd ./chrome/opt/google/chrome/
+    export PATH="$PWD:$PATH"
+    cd -
+
+    wget https://ftp.mozilla.org/pub/firefox/releases/138.0.1/linux-x86_64/en-GB/firefox-138.0.1.tar.xz
+    tar -xJf firefox-138.0.1.tar.xz
+    cd ./firefox
+    export PATH="$PWD:$PATH"
+    cd -
+
+    echo "Running test_xeus_cpp in Firefox"
+    python $BUILD_PREFIX/bin/emrun.py --browser="firefox" --kill_exit --timeout 60 --browser-args="--headless"  test_xeus_cpp.html
+    echo "Running test_xeus_cpp in Google Chrome"
+    python $BUILD_PREFIX/bin/emrun.py --browser="google-chrome" --kill_exit --timeout 60 --browser-args="--headless --no-sandbox"  test_xeus_cpp.html
+```
+
 To build Jupyter Lite with this kernel without creating a website you can execute the following
 ```bash
 micromamba create -n xeus-lite-host jupyterlite-core -c conda-forge
@@ -106,9 +157,3 @@ Once the Jupyter Lite site has built you can test the website locally by executi
 ```bash
 jupyter lite serve --XeusAddon.prefix=$PREFIX
 ```
-
-To test the lite build you can execute the following to run the C++ tests built against emscripten
-```bash
-cd test
-node test_xeus_cpp.js
-```
diff --git a/README.md b/README.md
@@ -95,6 +95,57 @@ emcmake cmake \
 emmake make install
 ```
 
+To test the lite build you can execute the following to run the C++ tests built against emscripten in node
+
+```bash
+cd test
+node test_xeus_cpp.js
+```
+
+It is possible to run the Emscripten tests in a headless browser. We will run our tests in a fresh installed browser. Installing the browsers, and running the tests within the installed browsers will be platform dependent. To do this on MacOS execute the following
+
+```bash
+    wget "https://download.mozilla.org/?product=firefox-latest&os=osx&lang=en-US" -O Firefox-latest.dmg
+    hdiutil attach Firefox-latest.dmg
+    cp -r /Volumes/Firefox/Firefox.app $PWD
+    hdiutil detach /Volumes/Firefox
+    cd ./Firefox.app/Contents/MacOS/
+    export PATH="$PWD:$PATH"
+    cd -
+
+    wget https://dl.google.com/chrome/mac/stable/accept_tos%3Dhttps%253A%252F%252Fwww.google.com%252Fintl%252Fen_ph%252Fchrome%252Fterms%252F%26_and_accept_tos%3Dhttps%253A%252F%252Fpolicies.google.com%252Fterms/googlechrome.pkg
+    pkgutil --expand-full googlechrome.pkg google-chrome
+    cd ./google-chrome/GoogleChrome.pkg/Payload/Google\ Chrome.app/Contents/MacOS/
+    export PATH="$PWD:$PATH"
+    cd -
+
+    echo "Running test_xeus_cpp in Firefox"
+    python $BUILD_PREFIX/bin/emrun.py --browser="firefox" --kill_exit --timeout 60 --browser-args="--headless"  test_xeus_cpp.html
+    echo "Running test_xeus_cpp in Google Chrome"
+    python python $BUILD_PREFIX/bin/emrun.py --browser="Google Chrome" --kill_exit --timeout 60 --browser-args="--headless  --no-sandbox"  test_xeus_cpp.html
+```
+
+To do this on Ubuntu x86 execute the following
+
+```bash
+    wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
+    dpkg-deb -x google-chrome-stable_current_amd64.deb $PWD/chrome
+    cd ./chrome/opt/google/chrome/
+    export PATH="$PWD:$PATH"
+    cd -
+
+    wget https://ftp.mozilla.org/pub/firefox/releases/138.0.1/linux-x86_64/en-GB/firefox-138.0.1.tar.xz
+    tar -xJf firefox-138.0.1.tar.xz
+    cd ./firefox
+    export PATH="$PWD:$PATH"
+    cd -
+
+    echo "Running test_xeus_cpp in Firefox"
+    python $BUILD_PREFIX/bin/emrun.py --browser="firefox" --kill_exit --timeout 60 --browser-args="--headless"  test_xeus_cpp.html
+    echo "Running test_xeus_cpp in Google Chrome"
+    python $BUILD_PREFIX/bin/emrun.py --browser="google-chrome" --kill_exit --timeout 60 --browser-args="--headless --no-sandbox"  test_xeus_cpp.html
+```
+
 To build Jupyter Lite with this kernel without creating a website you can execute the following
 ```bash
 micromamba create -n xeus-lite-host jupyterlite-core -c conda-forge
@@ -108,12 +159,6 @@ Once the Jupyter Lite site has built you can test the website locally by executi
 jupyter lite serve --XeusAddon.prefix=$PREFIX
 ```
 
-To test the lite build you can execute the following to run the C++ tests built against emscripten
-```bash
-cd test
-node test_xeus_cpp.js
-```
-
 ## Trying it online
 
 To try out xeus-cpp interactively in your web browser, just click on the binder link:

diff --git a/docs/source/InstallationAndUsage.rst b/docs/source/InstallationAndUsage.rst
@@ -82,6 +82,57 @@ You are now in a position to build the xeus-cpp kernel. You build it by executin
     emmake make install
 
 
+To test the lite build you can execute the following to run the C++ tests built against emscripten in node
+
+.. code-block:: bash
+
+    cd test
+    node test_xeus_cpp.js
+
+It is possible to run the Emscripten tests in a headless browser. We will run our tests in a fresh installed browser. Installing the browsers, and running the tests within the installed browsers will be platform dependent. To do this on MacOS execute the following
+
+.. code-block:: bash
+
+    wget "https://download.mozilla.org/?product=firefox-latest&os=osx&lang=en-US" -O Firefox-latest.dmg
+    hdiutil attach Firefox-latest.dmg
+    cp -r /Volumes/Firefox/Firefox.app $PWD
+    hdiutil detach /Volumes/Firefox
+    cd ./Firefox.app/Contents/MacOS/
+    export PATH="$PWD:$PATH"
+    cd -
+
+    wget https://dl.google.com/chrome/mac/stable/accept_tos%3Dhttps%253A%252F%252Fwww.google.com%252Fintl%252Fen_ph%252Fchrome%252Fterms%252F%26_and_accept_tos%3Dhttps%253A%252F%252Fpolicies.google.com%252Fterms/googlechrome.pkg
+    pkgutil --expand-full googlechrome.pkg google-chrome
+    cd ./google-chrome/GoogleChrome.pkg/Payload/Google\ Chrome.app/Contents/MacOS/
+    export PATH="$PWD:$PATH"
+    cd -
+
+    echo "Running test_xeus_cpp in Firefox"
+    python $BUILD_PREFIX/bin/emrun.py --browser="firefox" --kill_exit --timeout 60 --browser-args="--headless"  test_xeus_cpp.html
+    echo "Running test_xeus_cpp in Google Chrome"
+    python $BUILD_PREFIX/bin/emrun.py --browser="Google Chrome" --kill_exit --timeout 60 --browser-args="--headless  --no-sandbox"  test_xeus_cpp.html
+
+To do this on Ubuntu x86 execute the following
+
+.. code-block:: bash
+
+    wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
+    dpkg-deb -x google-chrome-stable_current_amd64.deb $PWD/chrome
+    cd ./chrome/opt/google/chrome/
+    export PATH="$PWD:$PATH"
+    cd -
+
+    wget https://ftp.mozilla.org/pub/firefox/releases/138.0.1/linux-x86_64/en-GB/firefox-138.0.1.tar.xz
+    tar -xJf firefox-138.0.1.tar.xz
+    cd ./firefox
+    export PATH="$PWD:$PATH"
+    cd -
+
+    echo "Running test_xeus_cpp in Firefox"
+    python $BUILD_PREFIX/bin/emrun.py --browser="firefox" --kill_exit --timeout 60 --browser-args="--headless"  test_xeus_cpp.html
+    echo "Running test_xeus_cpp in Google Chrome"
+    python $BUILD_PREFIX/bin/emrun.py --browser="google-chrome" --kill_exit --timeout 60 --browser-args="--headless --no-sandbox"  test_xeus_cpp.html
+
 To build Jupyter Lite with this kernel without creating a website you can execute the following
 
 .. code-block:: bash

diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt
@@ -56,7 +56,16 @@ if(EMSCRIPTEN)
     target_compile_options(test_xeus_cpp
         PUBLIC "SHELL: -fexceptions"
     )
-
+    # So we create a html file, as well as the javascript file
+    set_target_properties(test_xeus_cpp PROPERTIES
+        SUFFIX ".html"
+    )
+    # --emrun
+    # Makes it so that we run the html file created by this target, that we can capture the
+    # standard output and output it to the terminal
+    # MINIFY_HTML=0
+    # Without this MINIFY_HTML=0 flag you end up with the situation where the creation of the
+    # test_xeus_cpp.html file breaks on MacOS, but not Ubuntu
     target_link_options(test_xeus_cpp
         PUBLIC "SHELL: -fexceptions"
         PUBLIC "SHELL: -s MAIN_MODULE=1"
@@ -69,6 +78,8 @@ if(EMSCRIPTEN)
         PUBLIC "SHELL: --preload-file ${SYSROOT_PATH}/include@/include"
         PUBLIC "SHELL: --preload-file ../${XEUS_CPP_DATA_DIR}@/share/xeus-cpp"
         PUBLIC "SHELL: --preload-file ../${XEUS_CPP_CONF_DIR}@/etc/xeus-cpp"
+        PUBLIC "SHELL: --emrun"
+        PUBLIC "SHELL: -s MINIFY_HTML=0"
     )
 
     target_include_directories(test_xeus_cpp PRIVATE ${XEUS_CPP_INCLUDE_DIR})