Running Tests

Relevant source files

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

• package.json
• CONTRIBUTING.md
• README.md
• src/utils/validation.ts
• src/server.ts
• src/index.ts
• SECURITY.md

The gr8hopper project utilizes a comprehensive testing strategy to ensure code quality, security, and cross-platform compatibility between Node.js and Cloudflare Workers environments. The testing framework is built upon vitest, a modern and fast test runner.

Contributors are expected to run tests locally before submitting pull requests to verify their changes. The test suite covers core functionalities such as redirect logic, route pattern matching, and the admin API. This ensures that new features or fixes do not introduce regressions and adhere to the project's standards for performance and security.

Sources: CONTRIBUTING.md, package.json

Test Framework and Execution

The project uses vitest for its testing needs. The configuration and scripts for running tests are defined in package.json.

Sources: package.json:20-20

NPM Scripts

The following NPM scripts are available for testing and development:

Script	Command	Description
test	vitest run	Runs the entire test suite once.
dev	wrangler dev	Starts a local development server for Cloudflare Workers.
dev:node	tsx watch src/server.ts	Starts a local Node.js development server with hot-reloading.
lint	eslint src/ --max-warnings=0	Runs the linter to check for code style issues.
prepare	husky	Installs Git hooks using Husky.

Sources: package.json:11-21

To execute the test suite, run the following command from the project root:

npm test

This command invokes vitest run, which discovers and executes all test files in the repository.

Sources: package.json:20-20

Pre-commit Hooks

The project uses husky and lint-staged to enforce code quality before commits. This setup automatically runs eslint on staged files, ensuring that code style is consistent and potential errors are caught early in the development process.

Sources: package.json:22-28

Development and Testing Workflow

The CONTRIBUTING.md file outlines a clear workflow for developers to follow, which integrates testing as a core step.

The following diagram illustrates the recommended development and testing process.

Key Test Areas

Based on the project structure, the tests are organized to cover distinct functional areas of the application.

This diagram shows the relationship between source code modules and their corresponding tests.

Admin API

Tests for the admin API ensure that all endpoints for managing routes and settings are functioning correctly. This includes:

• Authentication: Verifying that all admin endpoints are protected by Basic Authentication. The server entry points (src/server.ts and src/index.ts) apply auth middleware to the /admin path.
• CRUD Operations: Testing the GET, POST, PUT, and DELETE methods for /admin/routes.
• Settings Management: Testing GET and PUT for /admin/settings.
• Import/Export: Verifying the functionality of /admin/import and /admin/export.

The following sequence diagram shows a typical test case for creating a new route via the admin API.

Redirect Logic

These tests focus on the core purpose of gr8hopper: redirecting URLs. Key aspects tested include:

• Template Substitution: Correctly replacing placeholders like {id} with values from query parameters.
• Reserved Placeholders: Ensuring {route} is automatically populated with the route ID.
• Query Parameter Passthrough: Verifying that enabling passthrough: true correctly appends source query parameters (like UTM tags) to the destination URL.
• Caching Headers: Checking for correct Cache-Control and CDN-Cache-Control headers on 301 responses.

Sources: README.md

Input Validation and Security

A critical part of the test suite is verifying the input validation logic found in src/utils/validation.ts. This is essential for the security and stability of the application.

• Route ID Patterns: validateRouteIdPattern is tested to ensure it correctly identifies valid and invalid patterns, preventing malformed route IDs.
• URL Schemes: isValidUrlScheme is tested to block dangerous schemes like javascript: and data:, only allowing http: and https:.
• Sanitization: sanitizeUrl is tested to confirm it strips control characters that could lead to CRLF injection attacks.
• Configuration Validation: Functions like validateRouteConfig and validateSettings are tested to ensure that only valid data is written to storage.

Sources: src/utils/validation.ts, SECURITY.md