ci: tests workflow (stubs, torch, js-syntax, e2e) + test docs

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

.github/workflows/tests.yml

@@ -0,0 +1,135 @@
+name: Tests
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: tests-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  pytest-stubs:
+    name: pytest (ComfyUI + torch stubbed)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: tests/requirements-ci.txt
+      - run: pip install -r tests/requirements-ci.txt
+      - name: Assert torch is NOT installed (this leg tests the stub path)
+        run: python -c "import importlib.util,sys; sys.exit(importlib.util.find_spec('torch') is not None)"
+      # expect: 137 passed, 15 skipped (the requires_torch tests)
+      - run: python -m pytest tests/ -q -ra --ignore=tests/e2e
+
+  pytest-torch:
+    name: pytest (real CPU torch)
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    env:
+      USCG_REQUIRE_TORCH: "1"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: tests/requirements-ci.txt
+      - name: Install CPU torch (same minor as the GPU box)
+        run: pip install "torch==2.13.*" --index-url https://download.pytorch.org/whl/cpu
+      - run: pip install -r tests/requirements-ci.txt
+      - run: python -c "import torch; print(torch.__version__); assert hasattr(torch, 'inference_mode')"
+      # expect: 152 passed, 0 skipped
+      - run: python -m pytest tests/ -q -ra --ignore=tests/e2e
+
+  js-syntax:
+    name: JS syntax
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: web/**/*.js (ES modules)
+        run: |
+          for f in $(find web -name '*.js'); do
+            node --input-type=module --check < "$f" || { echo "FAIL $f"; exit 1; }
+          done
+      - name: resources/*.js (plain scripts)
+        run: |
+          for f in resources/*.js; do
+            node --check "$f" || { echo "FAIL $f"; exit 1; }
+          done
+      - name: Assembled Dashboard page (all logic_*.js share ONE script scope)
+        run: |
+          python - <<'PY'
+          import os, re, sys
+          sys.path.insert(0, os.getcwd())
+          import html_generator
+          page = html_generator.get_html_template("ci", {"items": []}, "1")
+          bodies = re.findall(r"<script(?![^>]*\bsrc=)[^>]*>(.*?)</script>", page, re.S)
+          assert bodies, "no inline <script> found in the generated page"
+          out = os.environ.get("RUNNER_TEMP", ".")
+          for n, body in enumerate(bodies):
+              with open(os.path.join(out, f"bundle_{n}.js"), "w", encoding="utf-8") as fh:
+                  fh.write(body)
+          print(f"wrote {len(bodies)} script bodies to {out}")
+          PY
+          for f in "${RUNNER_TEMP:-.}"/bundle_*.js; do
+            node --check "$f" || { echo "FAIL $f"; exit 1; }
+          done
+      - name: node:test unit tests (tests/js, if present)
+        run: |
+          if [ -d tests/js ]; then
+            node --test tests/js/
+          else
+            echo "tests/js not present, skipping"
+          fi
+
+  e2e-dashboard:
+    name: Dashboard SPA (Playwright)
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      USCG_REQUIRE_E2E: "1"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: |
+            tests/requirements-ci.txt
+            tests/e2e/requirements.txt
+      - run: pip install -r tests/requirements-ci.txt -r tests/e2e/requirements.txt
+      - name: Cache Playwright browsers
+        id: pw
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/ms-playwright
+          key: pw-${{ runner.os }}-${{ hashFiles('tests/e2e/requirements.txt') }}
+      - name: Install Chromium (cache miss)
+        if: steps.pw.outputs.cache-hit != 'true'
+        run: python -m playwright install --with-deps --only-shell chromium
+      - name: Install Chromium system deps (cache hit)
+        if: steps.pw.outputs.cache-hit == 'true'
+        run: python -m playwright install-deps chromium
+      - run: python -m pytest tests/e2e -q -ra --browser chromium --tracing retain-on-failure --output test-results
+      - name: Upload traces
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-traces
+          path: test-results/
+          retention-days: 7

CONTRIBUTING.md

@@ -44,14 +44,22 @@ pip install -r requirements.txt
 ## Running tests
 
 ```bash
-python -m pytest tests/ -v
+# Python unit tests (ComfyUI + torch are stubbed): needs pytest, numpy, pillow
+pip install -r tests/requirements-ci.txt
+python -m pytest tests/ -q -ra --ignore=tests/e2e     # 137 passed, 15 skipped without torch
+
+# With real torch (e.g. ComfyUI's python), the 15 `requires_torch` tests run too.
+# USCG_REQUIRE_TORCH=1 makes them fail instead of skip if torch is missing:
+USCG_REQUIRE_TORCH=1 python -m pytest tests/ -q -ra --ignore=tests/e2e   # 152 passed
+
+# Dashboard SPA browser smoke test (Playwright, Chromium, no ComfyUI needed)
+pip install -r tests/e2e/requirements.txt
+python -m playwright install chromium
+python -m pytest tests/e2e -q -ra
 ```
 
-There are currently 46 tests covering:
-- LTX video config expansion and cache key logic
-- Sigma parser
-- Config expansion (Cartesian products)
-- `state_to_configs_json` transformer
+GitHub Actions (`.github/workflows/tests.yml`) runs four jobs on every push and PR: `pytest-stubs`, `pytest-torch` (CPU torch), `js-syntax` (`node --check` on `web/` and `resources/`, the assembled Dashboard page, and `node --test tests/js/` when that folder exists) and `e2e-dashboard`.
+Tests live in `tests/` and must not contain network or process-spawning code (no `socket`, `http.server`, `subprocess`, `urllib`): `tests/` ships in the registry zip and is yara-scanned.
 
 PRs that change Python logic should add tests where it's reasonable to do so.
 

README.md

@@ -1465,6 +1465,26 @@ This is a **hybrid application** with three layers:
 2. **JS Frontend Bridge** (`web/` directory) — Runs in the ComfyUI browser tab. Registers custom nodes, manages widget state, and forwards server events.
 3. **Dashboard SPA** (`resources/` directory) — Runs **inside an iframe** in the dashboard node. A standalone app with its own state management, virtual scrolling, and event handling.
 
+### Development / Tests
+
+```bash
+# Python unit tests (ComfyUI + torch are stubbed): needs pytest, numpy, pillow
+pip install -r tests/requirements-ci.txt
+python -m pytest tests/ -q -ra --ignore=tests/e2e     # 137 passed, 15 skipped without torch
+
+# With real torch (e.g. ComfyUI's python), the 15 `requires_torch` tests run too.
+# USCG_REQUIRE_TORCH=1 makes them fail instead of skip if torch is missing:
+USCG_REQUIRE_TORCH=1 python -m pytest tests/ -q -ra --ignore=tests/e2e   # 152 passed
+
+# Dashboard SPA browser smoke test (Playwright, Chromium, no ComfyUI needed)
+pip install -r tests/e2e/requirements.txt
+python -m playwright install chromium
+python -m pytest tests/e2e -q -ra
+```
+
+GitHub Actions (`.github/workflows/tests.yml`) runs four jobs on every push and PR: `pytest-stubs`, `pytest-torch` (CPU torch), `js-syntax` (`node --check` on `web/` and `resources/`, the assembled Dashboard page, and `node --test tests/js/` when that folder exists) and `e2e-dashboard`.
+Tests live in `tests/` and must not contain network or process-spawning code (no `socket`, `http.server`, `subprocess`, `urllib`): `tests/` ships in the registry zip and is yara-scanned.
+
 ### Key Gotchas for AI Development
 
 1. **Config Builder output is ALWAYS wrapped** — `config_builder_node.py` outputs `{"configs": [...], "_distribution": {...}}`. The `sampler_node.py` MUST unwrap the `"configs"` key before passing to `expand_configs()`. If you add new top-level keys to the config output, update the extraction logic in `sampler_node.py` lines 269-286.