Setup GitHub Actions test suite with Docker, Busted, Playwright, and Luacheck

.busted

@@ -0,0 +1,21 @@
+-- Busted configuration.
+-- See https://lunarmodules.github.io/busted/ for full docs.
+return {
+    _all = {
+        ROOT = { "spec" },
+        -- Any file ending in _spec.lua under spec/ is auto-discovered.
+        pattern = "_spec",
+        -- Helpers that set up the test environment / safeguards.
+        helper = "spec/spec_helper.lua",
+        -- Spec files can be run from the repo root.
+        lpath = "./?.lua;./?/init.lua;./spec/?.lua",
+        verbose = true,
+    },
+    default = {
+        output = "utfTerminal",
+    },
+    ci = {
+        output = "plainTerminal",
+        ["suppress-pending"] = false,
+    },
+}

.github/actions/install-snapcloud-deps/action.yml

@@ -0,0 +1,29 @@
+name: Install Snap!Cloud runtime + Lua deps
+description: >
+  Installs OpenResty from the upstream apt repo and the project's Lua
+  dependencies via bin/install-lua-deps.sh (which applies the C++14
+  workaround for the xml-1.1.3 rock). Intended for jobs that need to run
+  a real Lapis server (playwright, axe).
+
+runs:
+  using: composite
+  steps:
+    - name: Install OpenResty (apt)
+      shell: bash
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y --no-install-recommends \
+          wget gnupg ca-certificates lsb-release
+        wget -qO - https://openresty.org/package/pubkey.gpg \
+          | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/openresty.gpg
+        codename=$(lsb_release -sc)
+        echo "deb http://openresty.org/package/ubuntu $codename main" \
+          | sudo tee /etc/apt/sources.list.d/openresty.list
+        sudo apt-get update
+        sudo apt-get install -y openresty
+
+    - name: Install project Lua deps (with xml C++14 workaround)
+      shell: bash
+      # bin/install-lua-deps.sh forces CXX to gnu++14 so the xml-1.1.3 rock
+      # compiles on GCC 11 / clang 14+. Same script is used by `make install`.
+      run: SUDO=sudo LUA_VERSION=5.1 bin/install-lua-deps.sh

.github/actions/load-test-db/action.yml

@@ -0,0 +1,21 @@
+name: Load schema + seeds into snapcloud_test
+description: >
+  Runs db/schema.sql and db/seeds.sql against the postgres service
+  container. Assumes the usual CI env (DATABASE_HOST=127.0.0.1, user=cloud,
+  db=snapcloud_test) and a POSTGRES_PASSWORD input.
+
+inputs:
+  password:
+    description: Postgres password for the `cloud` user.
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - name: psql < db/schema.sql + db/seeds.sql
+      shell: bash
+      env:
+        PGPASSWORD: ${{ inputs.password }}
+      run: |
+        psql -h 127.0.0.1 -U cloud -d snapcloud_test -f db/schema.sql
+        psql -h 127.0.0.1 -U cloud -d snapcloud_test -f db/seeds.sql

.github/actions/run-browser-specs/action.yml

@@ -0,0 +1,73 @@
+name: Run Playwright browser specs
+description: >
+  Sets up Node + Playwright browsers, builds stylesheets, boots a Lapis
+  server, and runs a subset of the Playwright suite controlled by a grep
+  pattern. Used by both the `playwright` (grep-invert @axe) and `axe`
+  (grep @axe) jobs.
+
+inputs:
+  grep:
+    description: Playwright --grep pattern. Empty means no filter.
+    required: false
+    default: ""
+  grep-invert:
+    description: Playwright --grep-invert pattern. Empty means no filter.
+    required: false
+    default: ""
+  report-name:
+    description: Name used when uploading the Playwright HTML report artifact.
+    required: false
+    default: "playwright-report"
+
+runs:
+  using: composite
+  steps:
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: 20
+        cache: npm
+
+    - name: Install Node deps + Playwright browsers
+      shell: bash
+      run: |
+        npm ci
+        npx playwright install --with-deps chromium
+
+    - name: Build stylesheets
+      shell: bash
+      run: npx sass static/scss/:static/style/compiled/ --style compressed --no-source-map
+
+    - name: Start Lapis server
+      shell: bash
+      run: |
+        mkdir -p logs tmp store/test
+        lapis server test &
+        echo "Waiting for server to come up..."
+        for i in $(seq 1 30); do
+          if curl -fsS http://localhost:8080/ > /dev/null; then
+            echo "Server is up."
+            break
+          fi
+          sleep 1
+        done
+
+    - name: Run Playwright
+      shell: bash
+      run: |
+        args=""
+        if [ -n "${{ inputs.grep }}" ]; then
+          args="$args --grep \"${{ inputs.grep }}\""
+        fi
+        if [ -n "${{ inputs.grep-invert }}" ]; then
+          args="$args --grep-invert \"${{ inputs.grep-invert }}\""
+        fi
+        eval "npx playwright test $args"
+
+    - name: Upload Playwright report
+      if: always()
+      uses: actions/upload-artifact@v4
+      with:
+        name: ${{ inputs.report-name }}
+        path: playwright-report
+        retention-days: 7

.github/actions/setup-lua/action.yml

@@ -0,0 +1,43 @@
+name: Set up Lua 5.1 + luarocks
+description: >
+  Installs Lua 5.1, the dev headers, and luarocks from apt. Optionally
+  installs a list of tool rocks (luacheck, busted, luacov, etc.) from a
+  lockfile-free working directory so they don't drag in every project
+  dependency pinned in ./luarocks.lock.
+
+inputs:
+  tools:
+    description: >
+      Space-separated list of rock names to install globally, e.g.
+      "luacheck" or "busted luacov". Leave empty to only install Lua itself.
+    required: false
+    default: ""
+  postgres-client:
+    description: "Also install postgresql-client (for `psql`)."
+    required: false
+    default: "false"
+
+runs:
+  using: composite
+  steps:
+    - name: apt-get install lua5.1 + luarocks
+      shell: bash
+      run: |
+        sudo apt-get update
+        pkgs="lua5.1 liblua5.1-0-dev luarocks"
+        if [ "${{ inputs.postgres-client }}" = "true" ]; then
+          pkgs="$pkgs postgresql-client"
+        fi
+        sudo apt-get install -y $pkgs
+
+    - name: Install Lua tools (outside the project dir)
+      if: inputs.tools != ''
+      shell: bash
+      # Run from /tmp so luarocks doesn't auto-detect ./luarocks.lock and try
+      # to install every pinned project dependency as a prerequisite of the
+      # tool rock. Tools like luacheck/busted/luacov aren't project deps.
+      run: |
+        cd /tmp
+        for rock in ${{ inputs.tools }}; do
+          sudo luarocks install --lua-version=5.1 "$rock"
+        done

.github/workflows/ci.yml

@@ -0,0 +1,179 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Each job below reports its own status check. Keeping them independent means
+# a broken end-to-end test doesn't hide an a11y regression (or vice versa)
+# in the PR summary. Shared setup steps live in .github/actions/*.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+# Values reused across jobs. GHA workflow YAML doesn't let us anchor the
+# postgres `services:` block across jobs, but env + creds can at least be
+# pulled from one place.
+env:
+  PG_USER: cloud
+  PG_PASSWORD: snap-cloud-password
+  PG_DB: snapcloud_test
+
+jobs:
+  # ---------------------------------------------------------------------------
+  # Lint Lua code with luacheck. No DB, no server.
+  # ---------------------------------------------------------------------------
+  luacheck:
+    name: Luacheck
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - uses: ./.github/actions/setup-lua
+        with:
+          tools: luacheck
+      - run: luacheck .
+
+  # ---------------------------------------------------------------------------
+  # Unit tests for pure-Lua modules (busted). Needs postgres for the specs
+  # in spec/models/, but not OpenResty.
+  # ---------------------------------------------------------------------------
+  busted:
+    name: Busted (Lua)
+    runs-on: ubuntu-22.04
+
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: cloud
+          POSTGRES_PASSWORD: snap-cloud-password
+          POSTGRES_DB: snapcloud_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U cloud"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    env:
+      LAPIS_ENVIRONMENT: test
+      DATABASE_HOST: 127.0.0.1
+      DATABASE_PORT: 5432
+      DATABASE_USERNAME: cloud
+      DATABASE_PASSWORD: snap-cloud-password
+      DATABASE_NAME: snapcloud_test
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - uses: ./.github/actions/setup-lua
+        with:
+          tools: busted luacov
+          postgres-client: "true"
+      - uses: ./.github/actions/load-test-db
+        with:
+          password: snap-cloud-password
+      - run: busted --config-file=.busted --verbose
+
+  # ---------------------------------------------------------------------------
+  # End-to-end browser tests. Runs every Playwright spec NOT tagged @axe.
+  # ---------------------------------------------------------------------------
+  playwright:
+    name: Playwright (e2e)
+    runs-on: ubuntu-22.04
+
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: cloud
+          POSTGRES_PASSWORD: snap-cloud-password
+          POSTGRES_DB: snapcloud_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U cloud"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    env:
+      LAPIS_ENVIRONMENT: test
+      DATABASE_HOST: 127.0.0.1
+      DATABASE_PORT: 5432
+      DATABASE_USERNAME: cloud
+      DATABASE_PASSWORD: snap-cloud-password
+      DATABASE_NAME: snapcloud_test
+      PORT: 8080
+      HOSTNAME: localhost
+      CI: "true"
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - uses: ./.github/actions/setup-lua
+        with:
+          postgres-client: "true"
+      - uses: ./.github/actions/install-snapcloud-deps
+      - uses: ./.github/actions/load-test-db
+        with:
+          password: snap-cloud-password
+      - uses: ./.github/actions/run-browser-specs
+        with:
+          grep-invert: "@axe"
+          report-name: playwright-report
+
+  # ---------------------------------------------------------------------------
+  # Axe-core accessibility audit. Only @axe-tagged specs.
+  # ---------------------------------------------------------------------------
+  axe:
+    name: Axe-core (a11y)
+    runs-on: ubuntu-22.04
+
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: cloud
+          POSTGRES_PASSWORD: snap-cloud-password
+          POSTGRES_DB: snapcloud_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U cloud"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    env:
+      LAPIS_ENVIRONMENT: test
+      DATABASE_HOST: 127.0.0.1
+      DATABASE_PORT: 5432
+      DATABASE_USERNAME: cloud
+      DATABASE_PASSWORD: snap-cloud-password
+      DATABASE_NAME: snapcloud_test
+      PORT: 8080
+      HOSTNAME: localhost
+      CI: "true"
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - uses: ./.github/actions/setup-lua
+        with:
+          postgres-client: "true"
+      - uses: ./.github/actions/install-snapcloud-deps
+      - uses: ./.github/actions/load-test-db
+        with:
+          password: snap-cloud-password
+      - uses: ./.github/actions/run-browser-specs
+        with:
+          grep: "@axe"
+          report-name: axe-report

.gitignore

@@ -49,6 +49,13 @@ static/img/totm.png
 # local JS tools
 node_modules/
 
+# Test / CI artifacts
+/playwright-report/
+/test-results/
+/playwright/.cache/
+luacov.*.out
+.luacov_stats.out
+
 # Database Dumps and Backups
 *.dump
 *.db