Updates the e2e testing infrastructure to enable other licensing methods.

Author: pauldruce

.github/workflows/run-e2e-tests.yml

@@ -1,4 +1,4 @@
-# Copyright 2023 The MathWorks, Inc.
+# Copyright 2023-2024 The MathWorks, Inc.
 
 name: End-to-End Tests for Jupyter Integration for MATLAB
 on:
@@ -7,6 +7,9 @@ on:
 jobs:
   playwright_e2e_tests:
     runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: tests/e2e
     env:
       NODE_VERSION: 18
       PYTHON_VERSION: 3.8
@@ -18,17 +21,20 @@ jobs:
         with:
           node-version: ${{ env.NODE_VERSION }}
 
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
       - name: Install xvfb
         run: |
           sudo apt-get update
           sudo apt-get install -y xvfb
 
       - name: Install node dependencies
-        working-directory: ./tests/e2e
         run: npm ci
 
       - name: Run the linter
-        working-directory: ./tests/e2e
         run: npm run lint
 
       - name: Set up MATLAB
@@ -37,45 +43,59 @@ jobs:
         with:
           products: MATLAB Symbolic_Math_Toolbox
 
-      - name: Set up Python
-        uses: actions/setup-python@v4
-        with:
-          python-version: ${{ env.PYTHON_VERSION }}
+
 
       - name: Install jupyterlab and jupyter-matlab-proxy
+        working-directory: ${{ github.workspace }}
         run: |
           python3 -m pip install --upgrade pip
-          pip install ".[dev]"
-          pip install "jupyterlab>3.1.0,<4.0.0"
+          python3 -m pip install ".[dev]"
+          python3 -m pip install "jupyterlab>3.1.0,<4.0.0"
 
       - name: Install playwright browsers
-        working-directory: ./tests/e2e
         run: npx playwright install --with-deps
 
       - name: Find an available port
         run: |
-          FREE_PORT=$(python -c 'import socket; s=socket.socket(); s.bind(("", 0)); print(s.getsockname()[1]); s.close()');
+          FREE_PORT=$(python3 -c 'import socket; s=socket.socket(); s.bind(("", 0)); print(s.getsockname()[1]); s.close()');
           echo "Using port = ${FREE_PORT}"
           echo "TEST_JMP_PORT=$FREE_PORT" >> "$GITHUB_ENV"
 
-      # Playwright will start and stop the JupyterLab server, so we need
-      # to activate the Python venv. The command that is executed by Playwright
-      # is set by the webServer setting in the file playwright.config.ts
-      - name: Run playwright tests
-        working-directory: tests/e2e
+      - name: Start JupyterLab in background and save PID
+        id: start-jlab
+        run: |
+          npm start
+
+      - name: License MATLAB
         env:
           TEST_USERNAME: ${{ secrets.TEST_USERNAME }}
           TEST_PASSWORD: ${{ secrets.TEST_PASSWORD }}
+        run: |
+          python3 -m pip install --upgrade pip
+          python3 -m pip install pytest-playwright
+          python3 -m playwright install
+          python3 -c "from tests.utils.licensing import *; license_with_online_licensing(log_dir=\"./licensing-logs\")"
+
+      - name: Run playwright tests
+        env:
           TEST_JMP_PORT: ${{ env.TEST_JMP_PORT }}
         run: |
           echo "Playwright version: $(npx playwright -V)"
-          npx playwright test
+          npm test
+
+      - name: Stop JupyterLab
+        if: always()
+        run: |
+          npm stop
 
       - name: Zip test results
         if: always()
-        working-directory: tests/e2e
         run: |
-          zip -r zipped-e2e-test-results.zip ./playwright-report ./test-results
+          zip -r zipped-e2e-test-results.zip \
+            ./playwright-report \
+            ./test-results      \
+            ./licensing-logs \
+            ./jupyterlab.log
 
       - name: Preserve test results after the job has finished
         if: always()

.gitignore

@@ -14,3 +14,6 @@ playwright-report
 test-results
 .env
 .python-version
+jupyterlab.log
+jlab.pid
+licensing-logs

tests/README.md

@@ -102,14 +102,62 @@ a set of helpers and fixtures for JupyterLab UI exclusively in TypeScript.
 1. MATLAB (Version >= `R2020b`) in the system path
 2. NodeJS version 18 or higher.
 3. [MATLAB Proxy](https://github.com/mathworks/matlab-proxy) requirements
-4. MATLAB Proxy should be unlicensed
-6. Jupyter MATLAB Proxy requirements
-7. Valid MathWorks Account credentials
+4. Jupyter MATLAB Proxy requirements
+5. A way to license MATLAB
 
 
-### How to run the end-to-end tests
-* Set the environment variables TEST_USERNAME and TEST_PASSWORD to be your
-  MathWorks Account user credentials
+### Run the end-to-end tests
+#### Licensing Information
+The end-to-end tests require a licensed MATLAB to function.
+
+The simplest option is to ensure the MATLAB is licensed before you start the
+JupyterLab fixture, and set the environment variable
+`MWI_USE_EXISTING_LICENSE=true` before starting it.
+
+Another option is to license the MATLAB using the jupyter-matlab-proxy interface
+manually or by using the helper methods provided.
+These helper methods license the MATLAB via the matlab-proxy interface using
+online licensing.
+This approach is suitable for automation and can be used in CI systems.
+See the GitHub Actions Workflows in this repository for an example of how to do this.
+
+#### Setup
+* From the root directory of this project, install jupyter-matlab-proxy and
+  JupyterLab:
+  ```
+  pip install ".[dev]" "jupyterlab>=3.1.0,<4.0.0"
+  ```
+  MathWorks recommends using a Python virtual environment such as venv or conda.
+* From this repository's directory `tests/e2e`, install the node packages:
+  ```
+  npm install
+  ```
+  or to use the exact package version in the package-lock.json, use the command
+  `npm ci` instead.
+* Install the Playwright browsers:
+  ```
+  npx playwright install
+  ```
+
+#### Start the JupyterLab fixture
+The steps for starting the JupyterLab fixture depend on your licensing method.
+All steps assume you run them from the `tests/e2e` directory.
+
+If you are using an already licensed MATLAB:
+- Ensure you set the environment variable `MWI_USE_EXISTING_LICENSE=true` before
+  starting the JupyterLab instance.
+- Run the command `npm start`
+- Then run the tests: `npm test`
+
+If you are going to license the MATLAB using online licensing after starting the JupyterLab instance
+- Start the JupyterLab fixture:
+  ```
+  npm start
+  ```
+- License the MATLAB manually using the JupyterLab instance via the UI or by using the
+  helper methods provided. The steps for using the helper methods is outlined:
+  - Set the environment variables `TEST_USERNAME` and `TEST_PASSWORD` to your
+    MathWorks Account user credentials
     - Using a `.env` file (recommended):
       - Create a file called `.env` at the base of this repository, with the
         following lines:
@@ -123,37 +171,29 @@ a set of helpers and fixtures for JupyterLab UI exclusively in TypeScript.
         ```
         (if you don't want to use 'export' you can pass the environment
         variables in by prepending them to the Playwright test command below)
-    - Powershell (Windows):
+    - PowerShell (Windows):
         ```powershell
         $env:TEST_USERNAME="some-username"; $env:TEST_PASSWORD="some-password"
         ```
-* From the root directory of this project, install jupyter-matlab-proxy and
-  JupyterLab with the command:
+  - Use the helper functions provided:
     ```
-    pip install ".[dev]" "jupyterlab>=3.1.0,<4.0.0"
+    python3 -m pip install pytest-playwright
+    python3 -m playwright install
+    python3 -c "from tests.utils.licensing import *; license_with_online_licensing()"
     ```
-* From this repository's directory `/tests/e2e`, install the node packages using:
-  ```
-  npm install
-  ```
-  or to use the exact package version in the package-lock.json, use the command
-  `npm ci` instead.
-* Install the Playwright browsers with the command:
-  ```
-  npx playwright install
-  ```
-* Run the Playwright tests:
-  ```
-  npx playwright test
-  ```
-  If you don't want to use 'export' on your bash environment variables, you can pass in the
-  variables like this:
+
+#### Stop the JupyterLab Fixture
+* After testing has finished, stop the JupyterLab fixture by running the command
   ```
-  TEST_USERNAME="some-username" TEST_PASSWORD="some-password" npx playwright test
+  npm stop
   ```
+  or by using the JupyterLab UI.
+
+The default behaviour is for the logs of the JupyterLab instance to be written to
+a`jupyterlab.log` file in the `tests/e2e` directory.
 
 ----
 
-Copyright 2023 The MathWorks, Inc.
+Copyright 2023-2024 The MathWorks, Inc.
 
 ----

tests/e2e/jupyter_server_test_config.py

@@ -1,4 +1,4 @@
-# Copyright 2023 The MathWorks, Inc.
+# Copyright 2023-2024 The MathWorks, Inc.
 
 """
 JupyterLab Configuration
@@ -16,10 +16,17 @@
 is parsed by Jupyter and the below modifications to configuration class are
 applied.
 """
+import os
+from tempfile import mkdtemp
 
+# Allow JupyterLab to be started as root user
+c.ServerApp.allow_root = True
 
-from tempfile import mkdtemp
+# Listen on all IP Addresses - JLab defaults to only allowing requests from localhost.
+c.ServerApp.ip = "0.0.0.0"
 
+# Set the port to serve JupyterLab on.
+c.ServerApp.port = int(os.getenv("TEST_JMP_PORT", 8888))
 
 # Disable port retries
 c.ServerApp.port_retries = 0
@@ -31,10 +38,10 @@
 c.ServerApp.root_dir = mkdtemp(prefix="galata-test-")
 
 # Disable token-based authentication
-c.ServerApp.token = ""
+c.IdentityProvider.token = ""
 
 # Disable password-based authentication
-c.ServerApp.password = ""
+c.IdentityProvider.password = ""
 
 # Disable Cross-Site Request Forgery (CSRF) protection
 c.ServerApp.disable_check_xsrf = True
@@ -43,4 +50,4 @@
 c.LabApp.expose_app_in_browser = True
 
 # Set the log level to ERROR
-c.Application.log_level = "ERROR"
+c.Application.log_level = "INFO"