test.yml

# This is a GitHub workflow defining a set of jobs with a set of steps.
# ref: https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions
#
name: Test

on:
  pull_request:
    paths-ignore:
      - "docs/**"
      - "**.md"
      - "**.rst"
      - ".github/workflows/*"
      - "!.github/workflows/test.yml"
  push:
    paths-ignore:
      - "docs/**"
      - "**.md"
      - "**.rst"
      - ".github/workflows/*"
      - "!.github/workflows/test.yml"
    branches-ignore:
      - "dependabot/**"
      - "pre-commit-ci-update-config"
    tags:
      - "**"
  workflow_dispatch:

env:
  # UTF-8 content may be interpreted as ascii and causes errors without this.
  LANG: C.UTF-8
  SQLALCHEMY_WARN_20: "1"

permissions:
  contents: read

jobs:
  # Run "pytest jupyterhub/tests" in various configurations
  pytest:
    runs-on: ubuntu-20.04
    timeout-minutes: 15

    strategy:
      # Keep running even if one variation of the job fail
      fail-fast: false
      matrix:
        # We run this job multiple times with different parameterization
        # specified below, these parameters have no meaning on their own and
        # gain meaning on how job steps use them.
        #
        # subdomain:
        #   Tests everything when JupyterHub is configured to add routes for
        #   users with dedicated subdomains like user1.jupyter.example.com
        #   rather than jupyter.example.com/user/user1.
        #
        # db: [mysql/postgres]
        #   Tests everything when JupyterHub works against a dedicated mysql or
        #   postgresql server.
        #
        # legacy_notebook:
        #   Tests everything when the user instances are started with
        #   the legacy notebook server instead of jupyter_server.
        #
        # ssl:
        #   Tests everything using internal SSL connections instead of
        #   unencrypted HTTP
        #
        # main_dependencies:
        #   Tests everything when we use the latest available dependencies
        #   from: traitlets.
        #
        # NOTE: Since only the value of these parameters are presented in the
        #       GitHub UI when the workflow run, we avoid using true/false as
        #       values by instead duplicating the name to signal true.
        # Python versions available at:
        #   https://github.com/actions/python-versions/blob/HEAD/versions-manifest.json
        include:
          - python: "3.8"
            oldest_dependencies: oldest_dependencies
            legacy_notebook: legacy_notebook
          - python: "3.8"
            jupyter_server: "1.*"
            subset: singleuser
          - python: "3.9"
            db: mysql
          - python: "3.10"
            db: postgres
          - python: "3.11"
            subdomain: subdomain
            serverextension: serverextension
          - python: "3.11"
            ssl: ssl
            serverextension: serverextension
          - python: "3.11"
            jupyverse: jupyverse
            subset: singleuser
          - python: "3.11"
            subdomain: subdomain
            noextension: noextension
            subset: singleuser
          - python: "3.11"
            ssl: ssl
            noextension: noextension
            subset: singleuser
          - python: "3.11"
            browser: browser
          - python: "3.11"
            main_dependencies: main_dependencies

    steps:
      # NOTE: In GitHub workflows, environment variables are set by writing
      #       assignment statements to a file. They will be set in the following
      #       steps as if would used `export MY_ENV=my-value`.
      - name: Configure environment variables
        run: |
          if [ "${{ matrix.subdomain }}" != "" ]; then
              echo "JUPYTERHUB_TEST_SUBDOMAIN_HOST=http://localhost.jovyan.org:8000" >> $GITHUB_ENV
          fi
          if [ "${{ matrix.db }}" == "mysql" ]; then
              echo "MYSQL_HOST=127.0.0.1" >> $GITHUB_ENV
              echo "JUPYTERHUB_TEST_DB_URL=mysql+mysqldb://root@127.0.0.1:3306/jupyterhub" >> $GITHUB_ENV
          fi
          if [ "${{ matrix.ssl }}" == "ssl" ]; then
              echo "SSL_ENABLED=1" >> $GITHUB_ENV
          fi
          if [ "${{ matrix.db }}" == "postgres" ]; then
              echo "PGHOST=127.0.0.1" >> $GITHUB_ENV
              echo "PGUSER=test_user" >> $GITHUB_ENV
              echo "PGPASSWORD=hub[test/:?" >> $GITHUB_ENV
              echo "JUPYTERHUB_TEST_DB_URL=postgresql://test_user:hub%5Btest%2F%3A%3F@127.0.0.1:5432/jupyterhub" >> $GITHUB_ENV
          fi
          if [ "${{ matrix.serverextension }}" != "" ]; then
              echo "JUPYTERHUB_SINGLEUSER_EXTENSION=1" >> $GITHUB_ENV
          elif [ "${{ matrix.noextension }}" != "" ]; then
              echo "JUPYTERHUB_SINGLEUSER_EXTENSION=0" >> $GITHUB_ENV
          fi
          if [ "${{ matrix.jupyverse }}" != "" ]; then
              echo "JUPYTERHUB_SINGLEUSER_APP=jupyverse" >> $GITHUB_ENV
          fi
      - uses: actions/checkout@v4
      # NOTE: actions/setup-node@v4 make use of a cache within the GitHub base
      #       environment and setup in a fraction of a second.
      - name: Install Node v14
        uses: actions/setup-node@v4
        with:
          node-version: "14"
      - name: Install Javascript dependencies
        run: |
          npm install
          npm install -g configurable-http-proxy yarn
          npm list

      # NOTE: actions/setup-python@v5 make use of a cache within the GitHub base
      #       environment and setup in a fraction of a second.
      - name: Install Python ${{ matrix.python }}
        uses: actions/setup-python@v5
        with:
          python-version: "${{ matrix.python }}"

      - name: Install Python dependencies
        run: |
          pip install --upgrade pip

          if [ "${{ matrix.oldest_dependencies }}" != "" ]; then
            # frozen env with oldest dependencies
            # make sure our `>=` pins really do express our minimum supported versions
            pip install -r ci/oldest-dependencies/requirements.old -e .
          else
            pip install -e ".[test]"
          fi

          if [ "${{ matrix.main_dependencies }}" != "" ]; then
              # Tests are broken:
              # https://github.com/jupyterhub/jupyterhub/issues/4418
              # pip install git+https://github.com/ipython/traitlets#egg=traitlets --force
              pip install --upgrade --pre sqlalchemy
          fi
          if [ "${{ matrix.legacy_notebook }}" != "" ]; then
              pip uninstall jupyter_server --yes
              pip install 'notebook<7'
          fi
          if [ "${{ matrix.jupyter_server }}" != "" ]; then
              pip install "jupyter_server==${{ matrix.jupyter_server }}"
          fi
          if [ "${{ matrix.jupyverse }}" != "" ]; then
              pip install "jupyverse[jupyterlab,auth-jupyterhub]"
              pip install -e .
          fi
          if [ "${{ matrix.db }}" == "mysql" ]; then
              pip install mysqlclient
          fi
          if [ "${{ matrix.db }}" == "postgres" ]; then
              pip install psycopg2-binary
          fi
          if [ "${{ matrix.serverextension }}" != "" ]; then
            pip install 'jupyter-server>=2'
          fi

          pip freeze

      # NOTE: If you need to debug this DB setup step, consider the following.
      #
      # 1. mysql/postgressql are database servers we start as docker containers,
      #    and we use clients named mysql/psql.
      #
      # 2. When we start a database server we need to pass environment variables
      #    explicitly as part of the `docker run` command. These environment
      #    variables are named differently from the similarly named environment
      #    variables used by the clients.
      #
      #    - mysql    server ref: https://hub.docker.com/_/mysql/
      #    - mysql    client ref: https://dev.mysql.com/doc/refman/5.7/en/environment-variables.html
      #    - postgres server ref: https://hub.docker.com/_/postgres/
      #    - psql     client ref: https://www.postgresql.org/docs/9.5/libpq-envars.html
      #
      # 3. When we connect, they should use 127.0.0.1 rather than the
      #    default way of connecting which leads to errors like below both for
      #    mysql and postgresql unless we set MYSQL_HOST/PGHOST to 127.0.0.1.
      #
      #    - ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/var/run/mysqld/mysqld.sock' (2)
      #
      - name: Start a database server (${{ matrix.db }})
        if: ${{ matrix.db }}
        run: |
          if [ "${{ matrix.db }}" == "mysql" ]; then
            if [[ -z "$(which mysql)" ]]; then
              sudo apt-get update
              sudo apt-get install -y mysql-client
            fi
              DB=mysql bash ci/docker-db.sh
              DB=mysql bash ci/init-db.sh
          fi
          if [ "${{ matrix.db }}" == "postgres" ]; then
            if [[ -z "$(which psql)" ]]; then
              sudo apt-get update
              sudo apt-get install -y postgresql-client
            fi
              DB=postgres bash ci/docker-db.sh
              DB=postgres bash ci/init-db.sh
          fi

      - name: Configure browser tests
        if: matrix.browser
        run: echo "PYTEST_ADDOPTS=$PYTEST_ADDOPTS -m browser" >> "${GITHUB_ENV}"

      - name: Ensure browsers are installed for playwright
        if: matrix.browser
        run: python -m playwright install --with-deps

      - name: Run pytest
        run: |
          pytest -k "${{ matrix.subset }}" --maxfail=2 --cov=jupyterhub jupyterhub/tests

      - uses: codecov/codecov-action@v3

  docker-build:
    runs-on: ubuntu-20.04
    timeout-minutes: 20

    steps:
      - uses: actions/checkout@v4

      - name: build images
        run: |
          DOCKER_BUILDKIT=1 docker build -t jupyterhub/jupyterhub .
          docker build -t jupyterhub/jupyterhub-onbuild onbuild
          docker build -t jupyterhub/singleuser singleuser

      - name: smoke test jupyterhub
        run: |
          docker run --rm -t jupyterhub/jupyterhub jupyterhub --help

      - name: verify static files
        run: |
          docker run --rm -t -v $PWD/dockerfiles:/io jupyterhub/jupyterhub python3 /io/test.py