Add --run-browser-gui option and add documentation

Author: mcbarton

CONTRIBUTING.md

@@ -163,4 +163,43 @@ jupyter lite serve --XeusAddon.prefix=$PREFIX \
                    --contents notebooks/xeus-cpp-lite-demo.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 Test_Name --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 notebok_run with the notebook chosen for the Python script)
+
+```bash
+nbdiff notebook_run $HOME/Downlaods/notebook_run
+```
+
+For example after running the above test command, to test no changes have occured, execute
+
+```bash
+nbdiff xeus-cpp-lite-demo.ipynb $HOME/Downlaods/xeus-cpp-lite-demo.ipynb
+```
+
 ```

README.md

@@ -180,6 +180,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 Test_Name --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 notebok_run with the notebook chosen for the Python script)
+
+```bash
+nbdiff notebook_run $HOME/Downlaods/notebook_run
+```
+
+For example after running the above test command, to test no changes have occured, execute
+
+```bash
+nbdiff xeus-cpp-lite-demo.ipynb $HOME/Downlaods/xeus-cpp-lite-demo.ipynb
+```
+
 ## Trying it online
 
 To try out xeus-cpp interactively in your web browser, just click on the binder link:

docs/source/InstallationAndUsage.rst

@@ -161,6 +161,45 @@ 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 Test_Name --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 notebok_run with the notebook chosen for the Python script)
+
+.. code-block:: bash
+
+    nbdiff notebook_run $HOME/Downlaods/notebook_run
+
+
+For example after running the above test command, to test no changes have occured, execute
+
+.. code-block:: bash
+
+    nbdiff xeus-cpp-lite-demo.ipynb $HOME/Downlaods/xeus-cpp-lite-demo.ipynb
+		       
 Installing from conda-forge
 ===========================
 

scripts/automated-notebook-run-script.py

@@ -239,21 +239,28 @@ def main():
         default=120,
         help="Maximum time (in seconds) allowed for notebook execution before timeout.",
     )
-
+    parser.add_argument(
+        "--run-browser-gui",
+        action="store_true",
+        help="Run browser with a visible GUI (disables headless mode).",
+    )
+    
     args = parser.parse_args()
     URL = f"http://127.0.0.1:8000/lab/index.html?path={args.notebook}"
 
     # This will start the right driver depending on what
     # driver option is chosen
     if args.driver == "chrome":
         options = ChromeOptions()
-        options.add_argument("--headless")
-        options.add_argument("--no-sandbox")
+        if not args.run_browser_gui:
+            options.add_argument("--headless")
+            options.add_argument("--no-sandbox")
         driver = webdriver.Chrome(options=options)
 
     elif args.driver == "firefox":
         options = FirefoxOptions()
-        options.add_argument("--headless")
+        if not args.run_browser_gui:
+            options.add_argument("--headless")
         driver = webdriver.Firefox(options=options)
 
     elif args.driver == "safari":