Testing Strategy
Relevant source files
The following files were used as context for generating this wiki page:
The FOSSBilling branding project employs an automated testing strategy to ensure the integrity of generated visual assets and the accuracy of the asset manifest. The strategy focuses on validating the generate-assets.ts script, which handles SVG optimization, rasterization to PNG, and favicon creation.
Tests run using the native Node.js test runner and verify that the generation process produces valid files, maintains correct dimensions, and manages the file system safely without overwriting source files.
Sources: test/generate-assets.test.ts:12, package.json:7, README.md:94-100
Core Testing Components
The testing environment utilizes a fixture-based approach to isolate side effects and simulate various configuration states.
Test Fixtures
Each test case uses a fixture function to create a temporary directory for input and output. This function populates the directory with a mock master SVG and a sample export.config.json. It provides a generate helper to execute the asset generation script with specific arguments.
Sources: test/generate-assets.test.ts:16-36
Execution Environment
Tests are executed via npm test, which invokes the Node.js test runner. The environment requires Node.js 24 or newer to support the direct execution of TypeScript scripts and the native testing module.
Sources: package.json:6-10, tsconfig.json:11
Validation Categories
The testing strategy covers five primary functional areas to ensure the reliability of the asset pipeline.
1. Manifest Accuracy and Metadata
Tests verify that the manifest.json file correctly catalogs every exported asset. The test suite checks:
- Timestamping: The
exportedAtfield must be a valid UTC ISO string and match the execution time. - Dimensions: PNG files must have dimensions that match the manifest entries exactly.
- File Formats: The system confirms the presence of
.svg,.png, and.icofiles as defined in the configuration.
Sources: test/generate-assets.test.ts:38-70, scripts/types.ts:17-21
2. State Management and Cleanup
The test suite ensures that the generation script correctly manages the output directory over multiple runs.
- Obsolete Removal: When sizes or variants are removed from the configuration, the script must delete the corresponding files from the disk.
- Persistence: Files not managed by the branding script (e.g., manual notes) must remain untouched.
Sources: test/generate-assets.test.ts:72-91, scripts/generate-assets.ts:177-196
3. Safety and Security
Critical tests prevent the script from destructive actions on the source repository.
- Source Protection: The script throws an error and halts execution if an output path would overwrite a source master file.
- Symlink Safety: The system checks that the cleanup process does not follow symlinked directories, preventing accidental deletion of external files.
Sources: test/generate-assets.test.ts:104-127, scripts/generate-assets.ts:166-170
4. Input Validation
The strategy includes negative testing to verify how the system handles invalid states.
- Atomic Failures: If the configuration is invalid (e.g., missing source files), existing exports must remain intact and unchanged.
- SVG Requirements: The script rejects SVGs containing "live text" to ensure cross-platform compatibility without font dependencies.
Sources: test/generate-assets.test.ts:93-102, scripts/generate-assets.ts:108-111
5. Visual Preview Generation
The create-preview.ts logic is tested to ensure it produces an opaque PNG reference sheet. Tests validate:
- Dimensions: The preview must meet the fixed width (1200px) and dynamic height requirements.
- Color Composition: Pixel-level checks confirm that specific branding colors (e.g., FOSSBilling Blue
#0785BC) appear in the correct positions within the preview image.
Sources: test/generate-assets.test.ts:139-166, scripts/create-preview.ts:19-21
Asset Generation Flow
The following diagram illustrates the flow from source SVG and configuration to the validated outputs as exercised by the test suite.
This diagram shows the relationship between source assets, the generation logic, and the assertion points within the test suite.
Sources: scripts/generate-assets.ts:98-155, test/generate-assets.test.ts:44-55
Command Reference
| Command | Purpose | Source File |
|---|---|---|
npm test | Runs the automated test suite using Node's native runner. | package.json:7 |
npm run typecheck | Validates TypeScript syntax and type safety in scripts and tests. | package.json:8 |
npm run generate | Executes the asset generation script being tested. | package.json:6 |
Summary
The testing strategy ensures that FOSSBilling assets are consistent, optimized, and safely generated. By leveraging a strict manifest-based validation and file system safety checks, the project maintains high-quality branding assets across different background variants and display sizes.