Development and Testing

Development and Testing

WebSSH supports Python 3.11 and newer. The production container currently uses Python 3.14. The frontend is vanilla JavaScript and CSS with locally vendored dependencies.

Development setup

On Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --require-hashes -r requirements-test.txt
$env:SECRET_KEY = '<strong local development secret>'
.\.venv\Scripts\python.exe start.py

On Unix-like systems, use the corresponding .venv/bin/python interpreter and environment-variable syntax.

Do not reuse production DATA_DIR, credentials, or secrets for development and tests.

Dependency management

Direct Python dependencies live in requirements.in; hash-locked runtime and test files are generated by:

.\scripts\lock_requirements.ps1

Verify locks without modifying them:

.\scripts\lock_requirements.ps1 -Check

Do not hand-edit generated lock files. A dependency change must update the input, both lock outputs as applicable, and relevant compatibility tests.

Python tests

Run the suite with:

.\.venv\Scripts\python.exe -m pytest tests -q

The maintained gates execute tests on Python 3.11 and 3.14, exercise Redis 7/8 rate limiting, and include disposable OpenSSH integration. Targeted tests are useful while developing, but they do not replace the relevant full gate before release.

Frontend dependencies

Pinned browser libraries are declared in package.json and copied into the repository through the vendor workflow. Current contracts include xterm.js, fit/search addons, Socket.IO client, highlight.js, and Material Icons.

npm ci
npm run vendor
npm run vendor:check

Do not add runtime CDN scripts, fonts, or styles. The application must remain offline-capable and satisfy CSP and vendor-integrity tests.

JavaScript and E2E tests

npm run lint:js
npm run test:js
npm run test:e2e

Playwright assumptions must be updated when a default frontend state changes. Test both the new default and the user's explicit override, and bump template asset query versions when a cached browser asset changes.

Container and runtime gates

Relevant release validation includes:

• container build and startup;
• Gunicorn gthread, exactly one worker, and thread/socket reserve;
• /health and /ready behavior;
• graceful shutdown and transfer cleanup;
• AMD64 and ARM64 images;
• SPDX SBOM and provenance;
• Trivy results for fixable High/Critical findings;
• CodeQL for Python, JavaScript/TypeScript, and Actions.

Always associate CI evidence with the exact commit under review. A green run from an older SHA is not evidence for a newer change.

Storage and concurrency rules

When changing JSON persistence:

• hold storage_lock for the complete load-modify-save sequence;
• use atomic_write_json;
• preserve corrupt data for diagnosis rather than overwriting it;
• make schema migrations additive and backed up.

When changing SSH/SFTP or transfers:

• preserve user ownership checks;
• use existing Paramiko channel helpers;
• keep timeouts, cancellation, and quota admission;
• ensure quick connections outlive queued/active transfer references;
• test graceful shutdown and disconnect races.

Contributions

Keep changes focused and match the surrounding module's style and error contracts. Feature proposals belong in GitHub Discussions. Security vulnerabilities must follow the private process in SECURITY.md, not a public issue.

Before submitting a change, run the checks relevant to its actual blast radius and document any gate that could not be executed.