This directory contains the comprehensive modular test infrastructure for SWCanvas, with 36 core tests + 138 visual tests and cross-platform compatibility.
tests/
├── core/ # 36 individual core test files (001-036)
│ ├── 001-surface-creation-valid.js
│ ├── 015-alpha-blending-test.js
│ ├── 031-transform-matrix-order-dependency.js
│ └── ... (32 more files)
├── visual/ # 138 individual visual test files (001-138)
│ ├── 001-simple-rectangle-test.js
│ ├── 027-fill-rule-complex-test.js
│ ├── 056-stroke-pixel-analysis-test.js
│ └── ... (134 more files)
├── browser/ # Browser-specific test files
│ ├── index.html # Main browser test page (interactive + comparisons)
│ ├── simple-test.html # Simple visual comparison test
│ └── browser-test-helpers.js # Browser-specific interactive testing tools
├── dist/ # Built test files (auto-generated, .gitignored)
│ ├── core-functionality-tests.js # Auto-generated from /core/
│ └── visual-rendering-tests.js # Auto-generated from /visual/
├── build/
│ └── concat-tests.js # Build-time concatenation script
├── core-functionality-tests.js # Original (fallback/reference)
├── visual-rendering-tests.js # Original (fallback/reference)
├── run-tests.js # Smart test runner with auto-detection
├── output/ # Generated PNG test images (138+ files)
└── README.md # This file
# Build modular tests + run complete test suite
npm run build # Concatenates individual test files
npm test # Uses built modular tests automatically
# Or directly:
node tests/run-tests.js # Smart runner uses built tests when available
tests/browser/index.html in a web browser (automatically runs all tests on page load)/tests/core/tests/browser/simple-test.html for basic visual comparisonTechnical Note: Browser visual comparisons use renderSWCanvasToHTML5() helper function in build/concat-tests.js which correctly transfers SWCanvas Surface data (non-premultiplied RGBA) to HTML5 Canvas ImageData without unpremultiplication, ensuring accurate semi-transparent color display.
SWCanvas uses a modular complementary dual test system where individual test files are automatically concatenated at build time, maintaining both development flexibility and production performance:
Location: /tests/core/ (individual files) → /tests/dist/core-functionality-tests.js (concatenated)
Modular Structure:
Characteristics:
assertEquals(), assertThrows() assertionsTest Types:
Example Modular Test File (/tests/core/001-surface-creation-valid.js):
// Test: Surface creation with valid dimensions
// This file will be concatenated into the main test suite
// Test 001
test('Surface creation with valid dimensions', () => {
const surface = SWCanvas.Core.Surface(400, 300);
assertEquals(surface.width, 400);
assertEquals(surface.height, 300);
// ✓ Programmatic validation with assertions
});
Location: /tests/visual/ (individual files) → /tests/dist/visual-rendering-tests.js (concatenated)
Modular Structure:
Characteristics:
Test Categories:
Example Modular Test File (/tests/visual/002-alpha-blending-test.js):
// Test: Alpha Blending Test
// This file will be concatenated into the main visual test suite
// Test 2
registerVisualTest('alpha-test', {
name: 'Alpha blending test - semi-transparent rectangles',
width: 200, height: 150,
// Unified drawing function that works with both canvas types
draw: function(canvas) {
const ctx = canvas.getContext('2d');
ctx.fillStyle = 'red';
ctx.fillRect(20, 20, 80, 60);
ctx.globalAlpha = 0.5;
ctx.fillStyle = 'green';
ctx.fillRect(40, 40, 80, 60);
// → Generates BMP for pixel-perfect verification
}
});
Smart Delegation Pattern:
// core-functionality-tests.js
test('Alpha blending test - semi-transparent rectangles', () => {
// 1. Try to delegate to visual test for consistency
if (typeof VisualRenderingTests !== 'undefined') {
const visualTest = VisualRenderingTests.getTest('alpha-test');
if (visualTest) {
const surface = visualTest.drawSWCanvas(SWCanvas);
saveBMP(surface, 'alpha-test.bmp', 'alpha test', SWCanvas);
// 2. Add programmatic validation on top of visual test
const pixel = getPixelAt(surface, 60, 50); // Green over red area
assertEquals(pixel.r, 127); // Verify alpha blending math
return; // ✓ Both visual AND programmatic verification
}
}
// 3. Fallback inline test if visual test unavailable
// ... inline drawing and assertion code
});
Why This Architecture Works:
Benefits of Complementary Testing:
browser-visual-tests.js)Interactive tests requiring DOM and visual comparison:
For advanced test organization and renumbering utilities, see tests/build/README.md.
Create a new individual file in /tests/core/ with the naming pattern {3-digit-number}-{descriptive-name}.js:
# Create new core test
echo "// Test: New feature test" > tests/core/032-new-feature-test.js
echo "test('New feature test', () => { /* test code */ });" >> tests/core/032-new-feature-test.js
# Build automatically includes it
npm run build && npm test
Create a new individual file in /tests/visual/ with the naming pattern {3-digit-number}-{descriptive-name}.js:
# Create new visual test
cat > tests/visual/057-new-visual-test.js << 'EOF'
// Test: New Visual Test
// This file will be concatenated into the main visual test suite
registerVisualTest('new-visual-test', {
name: 'New visual feature test',
width: 200, height: 150,
draw: function(canvas) {
const ctx = canvas.getContext('2d');
// Standard HTML5 Canvas API works with both implementations
ctx.fillStyle = 'blue';
ctx.fillRect(10, 10, 100, 100);
}
});
EOF
# Build automatically includes it
npm run build && npm test
Add interactive tests to browser-visual-tests.js for features requiring DOM interaction or real-time visual comparison.
Key Benefits of Modular Approach:
SWCanvas uses a 1-bit stencil buffer approach for clipping:
Standard HTML5 Canvas API ensures consistent colors:
ctx.fillStyle and ctx.strokeStyle with CSS color names