Automated Testing & CI

Relevant source files

The following files were used as context for generating this wiki page:

• test/app.test.js
• test/editor.browser.test.js
• PLAN.md
• package.json
• src/server.js
• src/util.js

Automated testing in PuppyPad ensures the stability of core features including user authentication, file management, and security constraints. The project utilizes node:test as the primary test runner, supplemented by supertest for HTTP assertions and playwright for end-to-end browser testing.

The Continuous Integration (CI) pipeline, defined in .github/workflows/ci.yml, executes the test suite, performs security audits via npm audit, and validates server configurations. This automated process verifies every push to ensure that changes do not break existing functionality or introduce security vulnerabilities like path traversal or phishing vectors.
Sources: PLAN.md:218-228, package.json:6-9

Testing Architecture

The PuppyPad test suite is divided into unit/integration tests and browser-based end-to-end tests. Tests run against a temporary data directory to ensure isolation and prevent side effects on development or production data.

The diagram shows the relationship between the test runner, specific test files, and the underlying testing tools that exercise the PuppyPad application.
Sources: test/app.test.js:9-25, test/editor.browser.test.js:10-25

Environment Configuration for Testing

To maintain environment purity, the test runner overrides several environment variables before loading the application. This setup prevents the test suite from interacting with real mail servers or third-party CAPTCHA services.

Variable	Test Value	Purpose
DATA_DIR	os.tmpdir() path	Isolated storage for test databases and files.
BASE_URL	http://pad.test	Mock domain for host-based routing tests.
ADMIN_EMAILS	boss@example.com	Defined administrator for access control tests.
SHOT_TOKEN	test-shot-token	Authentication for internal screenshot worker API.
SMTP_HOST	undefined	Disables real email sending.

Sources: test/app.test.js:9-20, test/editor.browser.test.js:10-16

Integration Testing (test/app.test.js)

Integration tests verify the backend logic by simulating HTTP requests. These tests cover the entire lifecycle of a user site, from signup to deletion.

Security and Validation Logic

The suite validates that the application correctly handles security threats and naming constraints:

• Path Traversal: Confirms that safeRel prevents access to files outside the member's directory (e.g., ../.env).
• Phishing Detection: Validates the phishSignals helper by checking for password fields or brand names in user-submitted HTML.
• CSRF Protection: Verifies that state-changing forms (POST) require a valid _csrf token and a matching Origin header.
• Rate Limiting: Tests that login, signup, and report submissions are capped per IP or account.

Sources: test/app.test.js:40-90, test/app.test.js:160-190

File and Quota Management

Tests exercise the file system logic to ensure limits are respected:

• Quota Enforcement: Verifies that uploads fail once a user exceeds the QUOTA_MB limit.
• Zip Import: Confirms that .zip files are unpacked correctly while filtering out disallowed file types or directory traversal attempts.
• Atomic Writes: Ensures that file saves do not leave corrupted half-written files on failure.

The sequence illustrates the multi-step validation process performed during a file upload test.
Sources: test/app.test.js:92-120, test/app.test.js:210-250

Browser Testing (test/editor.browser.test.js)

Browser tests use Playwright to verify client-side behavior in the in-browser code editor. This ensures that the CodeMirror integration and PuppyPad-specific editor enhancements function correctly.

Editor Functionality Verification

The browser test suite automates a Chromium instance to perform the following actions:

1. Authentication: Signs up a new user and verifies the email via the mock console log.
2. Tag Autocomplete: Types <di and waits for the .CodeMirror-hint selector to verify that <div> is suggested.
3. Auto-closing Tags: Types > after a tag and verifies the editor automatically appends the closing tag.
4. Find and Replace: Uses the replace dialog to swap text matches across the entire document.

Sources: test/editor.browser.test.js:37-77

CI Pipeline Integration

PuppyPad uses GitHub Actions for Continuous Integration. The pipeline is designed to "fail closed," meaning any failure in security or quality checks prevents the deployment of the code.

Pipeline Steps

• Audit: Runs npm audit --omit=dev to detect high-severity vulnerabilities in production dependencies.
• Validation: Executes caddy validate on the Caddyfile to ensure proxy configurations are correct.
• Execution: Runs the full test suite using node --test.
• Browser Setup: CI installs Chromium specifically for the browser tests; these tests are skipped in environments where no browser is found unless process.env.CI is set.

Sources: PLAN.md:218-228, test/editor.browser.test.js:4-6, package.json:6-9

Summary of Test Coverage

Category	File	Key Tests
Routing	app.test.js	Reserved names, Subdomain serving, Clean URLs, 404/410 states.
Security	app.test.js	CSRF, Phishing flags, Path traversal, TOTP/2FA flows.
Features	app.test.js	Zip import/export, Style editor, Webring, Guestbook moderation.
Frontend	editor.browser.test.js	CodeMirror hints, Tag closing, UI dialogs.
Maintenance	app.test.js	Housekeeping (IP purging), Disk health checks.

Sources: test/app.test.js:1-550, test/editor.browser.test.js:1-79