jsgui3-server 0.0.138 → 0.0.140

package/tests/README.md

@@ -0,0 +1,250 @@
+# JSGUI3 Minification, Compression & Sourcemaps Test Suite
+
+This comprehensive test suite validates the minification, compression, and sourcemap features implemented in JSGUI3 Server.
+
+## Overview
+
+The test suite covers all aspects of the Phase 1 implementation:
+
+- **Component Isolation Tests**: Test each bundler, assigner, and publisher in isolation
+- **Configuration Validation Tests**: Test all configuration options and validation
+- **End-to-End Integration Tests**: Run full server and test HTML/CSS/JS serving
+- **Content Analysis Tests**: Examine served content for proper minification, compression, and sourcemaps
+- **Performance Tests**: Test compression ratios and response sizes
+- **Error Handling Tests**: Test invalid configurations and edge cases
+
+## Test Structure
+
+```
+tests/
+├── bundlers.test.js              # Component isolation tests for bundlers
+├── assigners.test.js             # Component isolation tests for assigners
+├── publishers.test.js            # Component isolation tests for publishers
+├── configuration-validation.test.js  # Configuration validation tests
+├── end-to-end.test.js            # Full integration tests
+├── content-analysis.test.js      # Content analysis and verification
+├── performance.test.js           # Performance benchmarks
+├── error-handling.test.js        # Error handling and edge cases
+├── test-runner.js                # Custom test runner with reporting
+└── README.md                     # This file
+```
+
+## Running Tests
+
+### Run All Tests
+```bash
+npm test
+```
+
+### Run Specific Test Suite
+```bash
+# Using the custom test runner
+node tests/test-runner.js --test=bundlers.test.js
+
+# Using mocha directly
+npx mocha tests/bundlers.test.js
+```
+
+### Run Tests with Options
+```bash
+# Debug mode (enables sourcemaps)
+node tests/test-runner.js --debug
+
+# Verbose output
+node tests/test-runner.js --verbose
+
+# Specific test with debug
+node tests/test-runner.js --test=end-to-end.test.js --debug
+```
+
+## Test Coverage
+
+### 1. Component Isolation Tests (`bundlers.test.js`, `assigners.test.js`, `publishers.test.js`)
+
+Test each component independently:
+
+- **Bundlers**: ESBuild integration, minification levels, sourcemap generation
+- **Assigners**: Compression algorithms, statistics tracking, threshold handling
+- **Publishers**: Configuration validation, component integration
+
+### 2. Configuration Validation Tests (`configuration-validation.test.js`)
+
+Validate all configuration options:
+
+- Minification levels (`conservative`, `normal`, `aggressive`)
+- Compression algorithms (`gzip`, `br`) and settings
+- Sourcemap formats (`inline`, `external`) and conditions
+- Threshold and exclusion rules
+- Type validation and error messages
+
+### 3. End-to-End Integration Tests (`end-to-end.test.js`)
+
+Full server integration testing:
+
+- HTTP server startup with various configurations
+- Content negotiation (gzip/br/identity)
+- Minification and compression pipeline
+- Concurrent request handling
+- Error scenarios (port conflicts, invalid configs)
+
+### 4. Content Analysis Tests (`content-analysis.test.js`)
+
+Verify content integrity and correctness:
+
+- Minification effectiveness and ratios
+- Compression integrity (decompression verification)
+- Sourcemap generation and validation
+- CSS extraction and preservation
+- Bundle content structure
+
+### 5. Performance Tests (`performance.test.js`)
+
+Benchmark and analyze performance:
+
+- Bundling speed across different file sizes
+- Compression performance (gzip vs brotli)
+- Memory usage analysis
+- Server response times
+- Concurrent operation handling
+
+### 6. Error Handling Tests (`error-handling.test.js`)
+
+Comprehensive error scenario testing:
+
+- Invalid JavaScript syntax
+- File system errors (permissions, missing files)
+- Configuration validation errors
+- Network and HTTP errors
+- Memory and performance limits
+- Encoding issues
+
+## Configuration Examples
+
+### Basic Minification
+```javascript
+Server.serve({
+    ctrl: MyControl,
+    debug: false,  // Enables minification
+    bundler: {
+        minify: {
+            enabled: true,
+            level: 'normal'
+        }
+    }
+});
+```
+
+### Full Optimization Pipeline
+```javascript
+Server.serve({
+    ctrl: MyControl,
+    debug: false,
+    bundler: {
+        minify: {
+            enabled: true,
+            level: 'aggressive',
+            options: {
+                drop_console: true
+            }
+        },
+        sourcemaps: {
+            enabled: true,
+            format: 'inline'
+        },
+        compression: {
+            enabled: true,
+            algorithms: ['gzip', 'br'],
+            threshold: 1024
+        }
+    }
+});
+```
+
+## Test Results and Reporting
+
+The test runner generates:
+
+- **Console Output**: Real-time test progress and results
+- **JSON Report**: Detailed results saved to `test-report.json`
+- **Summary Statistics**: Pass/fail counts, success rates, timing
+
+### Sample Output
+```
+🚀 Starting JSGUI3 Minification, Compression & Sourcemaps Test Suite
+
+================================================================================
+📋 Running bundlers.test.js...
+✅ bundlers.test.js passed
+📋 Running assigners.test.js...
+✅ assigners.test.js passed
+...
+================================================================================
+📊 TEST SUMMARY
+================================================================================
+Total Test Suites: 8
+✅ Passed: 8
+❌ Failed: 0
+⚠️  Skipped: 0
+⏱️  Duration: 45.23s
+📈 Success Rate: 100.0%
+
+🎉 All tests passed! The minification, compression, and sourcemap features are working correctly.
+```
+
+## Environment Requirements
+
+- Node.js >= 15.0.0
+- Mocha test framework (included in package.json)
+- ESBuild (included in package.json)
+- zlib (built-in Node.js module)
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Port conflicts**: Tests use specific ports (3001-3005). Ensure these are available.
+
+2. **Memory issues**: Large content tests may require increased Node.js memory:
+   ```bash
+   node --max-old-space-size=4096 tests/test-runner.js
+   ```
+
+3. **File permissions**: Tests create temporary files. Ensure write permissions in the tests directory.
+
+4. **Slow tests**: Performance tests may take longer on resource-constrained systems.
+
+### Debug Mode
+
+Enable debug mode for additional logging:
+```bash
+export JSGUI_DEBUG=1
+node tests/test-runner.js
+```
+
+## Contributing
+
+When adding new tests:
+
+1. Follow the existing naming convention: `*.test.js`
+2. Add the new test file to `test-runner.js`
+3. Update this README with new test descriptions
+4. Ensure tests are isolated and don't interfere with each other
+5. Include both positive and negative test cases
+
+## Integration with CI/CD
+
+The test suite is designed to work with continuous integration:
+
+```yaml
+# Example GitHub Actions
+- name: Run Test Suite
+  run: npm test
+
+- name: Upload Test Results
+  uses: actions/upload-artifact@v2
+  with:
+    name: test-results
+    path: test-report.json
+```
+
+This ensures the minification, compression, and sourcemap features maintain their functionality across code changes.

package/tests/assigners.test.js

@@ -0,0 +1,316 @@
+const assert = require('assert');
+const { describe, it, beforeEach, afterEach } = require('mocha');
+
+// Import assigner classes
+const Single_Control_Webpage_Server_Static_Compressed_Response_Buffers_Assigner = require('../publishers/helpers/assigners/static-compressed-response-buffers/Single_Control_Webpage_Server_Static_Compressed_Response_Buffers_Assigner');
+
+describe('Assigner Component Isolation Tests', function() {
+    this.timeout(10000); // Increase timeout for compression operations
+
+    let mockBundleItems;
+
+    beforeEach(function() {
+        // Create mock bundle items for testing
+        mockBundleItems = [
+            {
+                type: 'HTML',
+                extension: 'html',
+                text: '<!DOCTYPE html><html><head><title>Test</title></head><body><h1>Hello World</h1></body></html>',
+                response_buffers: {}
+            },
+            {
+                type: 'JavaScript',
+                extension: 'js',
+                text: 'function test(){console.log("test");return"result";}test();',
+                response_buffers: {}
+            },
+            {
+                type: 'CSS',
+                extension: 'css',
+                text: '.test-class{color:red;font-size:14px;}.another-class{background:blue;}',
+                response_buffers: {}
+            }
+        ];
+
+        // Initialize identity buffers (simulate what uncompressed assigner would do)
+        mockBundleItems.forEach(item => {
+            item.response_buffers.identity = Buffer.from(item.text, 'utf8');
+        });
+    });
+
+    describe('Single_Control_Webpage_Server_Static_Compressed_Response_Buffers_Assigner', function() {
+        it('should compress content with default gzip settings', async function() {
+            const assigner = new Single_Control_Webpage_Server_Static_Compressed_Response_Buffers_Assigner();
+
+            await assigner.assign(mockBundleItems);
+
+            // Verify gzip compression was applied
+            mockBundleItems.forEach(item => {
+                assert(item.response_buffers.gzip, `Item ${item.type} should have gzip buffer`);
+                assert(Buffer.isBuffer(item.response_buffers.gzip), 'Gzip buffer should be a Buffer');
+
+                // Compressed content should be smaller than original (for non-trivial content)
+                if (item.response_buffers.identity.length > 100) {
+                    assert(item.response_buffers.gzip.length <= item.response_buffers.identity.length,
+                           `Gzip compressed ${item.type} should be smaller or equal size`);
+                }
+            });
+
+            // Verify compression statistics
+            assert.strictEqual(assigner.compression_stats.total_items, 3, 'Should track 3 total items');
+            assert.strictEqual(assigner.compression_stats.gzip_compressed, 3, 'Should have compressed 3 items with gzip');
+            assert(assigner.compression_stats.gzip_savings >= 0, 'Gzip savings should be non-negative');
+        });
+
+        it('should compress content with default brotli settings', async function() {
+            const assigner = new Single_Control_Webpage_Server_Static_Compressed_Response_Buffers_Assigner();
+
+            await assigner.assign(mockBundleItems);
+
+            // Verify brotli compression was applied
+            mockBundleItems.forEach(item => {
+                assert(item.response_buffers.br, `Item ${item.type} should have brotli buffer`);
+                assert(Buffer.isBuffer(item.response_buffers.br), 'Brotli buffer should be a Buffer');
+
+                // Compressed content should be smaller than original (for non-trivial content)
+                if (item.response_buffers.identity.length > 100) {
+                    assert(item.response_buffers.br.length <= item.response_buffers.identity.length,
+                           `Brotli compressed ${item.type} should be smaller or equal size`);
+                }
+            });
+
+            // Verify compression statistics
+            assert.strictEqual(assigner.compression_stats.brotli_compressed, 3, 'Should have compressed 3 items with brotli');
+            assert(assigner.compression_stats.brotli_savings >= 0, 'Brotli savings should be non-negative');
+        });
+
+        it('should respect compression configuration - gzip only', async function() {
+            const assigner = new Single_Control_Webpage_Server_Static_Compressed_Response_Buffers_Assigner({
+                compression: {
+                    enabled: true,
+                    algorithms: ['gzip']
+                }
+            });
+
+            await assigner.assign(mockBundleItems);
+
+            // Should have gzip but not brotli
+            mockBundleItems.forEach(item => {
+                assert(item.response_buffers.gzip, `Item ${item.type} should have gzip buffer`);
+                assert(!item.response_buffers.br, `Item ${item.type} should not have brotli buffer`);
+            });
+
+            assert.strictEqual(assigner.compression_stats.gzip_compressed, 3);
+            assert.strictEqual(assigner.compression_stats.brotli_compressed, 0);
+        });
+
+        it('should respect compression configuration - brotli only', async function() {
+            const assigner = new Single_Control_Webpage_Server_Static_Compressed_Response_Buffers_Assigner({
+                compression: {
+                    enabled: true,
+                    algorithms: ['br']
+                }
+            });
+
+            await assigner.assign(mockBundleItems);
+
+            // Should have brotli but not gzip
+            mockBundleItems.forEach(item => {
+                assert(!item.response_buffers.gzip, `Item ${item.type} should not have gzip buffer`);
+                assert(item.response_buffers.br, `Item ${item.type} should have brotli buffer`);
+            });
+
+            assert.strictEqual(assigner.compression_stats.gzip_compressed, 0);
+            assert.strictEqual(assigner.compression_stats.brotli_compressed, 3);
+        });
+
+        it('should respect compression configuration - custom gzip level', async function() {
+            const assigner = new Single_Control_Webpage_Server_Static_Compressed_Response_Buffers_Assigner({
+                compression: {
+                    enabled: true,
+                    algorithms: ['gzip'],
+                    gzip: { level: 1 } // Fastest compression
+                }
+            });
+
+            await assigner.assign(mockBundleItems);
+
+            // Should have gzip with custom level
+            mockBundleItems.forEach(item => {
+                assert(item.response_buffers.gzip, `Item ${item.type} should have gzip buffer`);
+                assert(!item.response_buffers.br, `Item ${item.type} should not have brotli buffer`);
+            });
+        });
+
+        it('should respect compression configuration - custom brotli quality', async function() {
+            const assigner = new Single_Control_Webpage_Server_Static_Compressed_Response_Buffers_Assigner({
+                compression: {
+                    enabled: true,
+                    algorithms: ['br'],
+                    brotli: { quality: 1 } // Lowest quality (fastest)
+                }
+            });
+
+            await assigner.assign(mockBundleItems);
+
+            // Should have brotli with custom quality
+            mockBundleItems.forEach(item => {
+                assert(!item.response_buffers.gzip, `Item ${item.type} should not have gzip buffer`);
+                assert(item.response_buffers.br, `Item ${item.type} should have brotli buffer`);
+            });
+        });
+
+        it('should skip compression when disabled', async function() {
+            const assigner = new Single_Control_Webpage_Server_Static_Compressed_Response_Buffers_Assigner({
+                compression: {
+                    enabled: false
+                }
+            });
+
+            await assigner.assign(mockBundleItems);
+
+            // Should not add any compressed buffers
+            mockBundleItems.forEach(item => {
+                assert(!item.response_buffers.gzip, `Item ${item.type} should not have gzip buffer when disabled`);
+                assert(!item.response_buffers.br, `Item ${item.type} should not have brotli buffer when disabled`);
+            });
+
+            // Statistics should be zero
+            assert.strictEqual(assigner.compression_stats.total_items, 0);
+            assert.strictEqual(assigner.compression_stats.gzip_compressed, 0);
+            assert.strictEqual(assigner.compression_stats.brotli_compressed, 0);
+        });
+
+        it('should respect compression threshold', async function() {
+            // Create a very small item that should be below threshold
+            const smallItem = {
+                type: 'JavaScript',
+                extension: 'js',
+                text: 'x=1', // Very small content
+                response_buffers: {
+                    identity: Buffer.from('x=1', 'utf8')
+                }
+            };
+
+            const assigner = new Single_Control_Webpage_Server_Static_Compressed_Response_Buffers_Assigner({
+                compression: {
+                    enabled: true,
+                    threshold: 1000 // High threshold
+                }
+            });
+
+            await assigner.assign([smallItem]);
+
+            // Small item should be skipped
+            assert(!smallItem.response_buffers.gzip, 'Small item should not be gzip compressed');
+            assert(!smallItem.response_buffers.br, 'Small item should not be brotli compressed');
+
+            // Statistics should reflect skipping
+            assert.strictEqual(assigner.compression_stats.total_items, 1);
+            assert.strictEqual(assigner.compression_stats.gzip_compressed, 0);
+            assert.strictEqual(assigner.compression_stats.brotli_compressed, 0);
+        });
+
+        it('should handle items without text property', async function() {
+            const itemWithoutText = {
+                type: 'Image',
+                extension: 'png',
+                response_buffers: {
+                    identity: Buffer.from('fake image data', 'utf8')
+                }
+            };
+
+            const assigner = new Single_Control_Webpage_Server_Static_Compressed_Response_Buffers_Assigner();
+
+            await assigner.assign([itemWithoutText]);
+
+            // Should not crash and should not add compression
+            assert(!itemWithoutText.response_buffers.gzip);
+            assert(!itemWithoutText.response_buffers.br);
+        });
+
+        it('should handle empty bundle array', async function() {
+            const assigner = new Single_Control_Webpage_Server_Static_Compressed_Response_Buffers_Assigner();
+
+            await assigner.assign([]);
+
+            // Should not crash
+            assert.strictEqual(assigner.compression_stats.total_items, 0);
+        });
+
+        it('should calculate compression ratios correctly', async function() {
+            const assigner = new Single_Control_Webpage_Server_Static_Compressed_Response_Buffers_Assigner({
+                compression: {
+                    enabled: true,
+                    algorithms: ['gzip']
+                }
+            });
+
+            // Use a larger text that will definitely compress
+            const largeText = 'console.log("'.repeat(1000) + '");';
+            const largeItem = {
+                type: 'JavaScript',
+                extension: 'js',
+                text: largeText,
+                response_buffers: {
+                    identity: Buffer.from(largeText, 'utf8')
+                }
+            };
+
+            await assigner.assign([largeItem]);
+
+            // Verify compression savings calculation
+            const originalSize = largeItem.response_buffers.identity.length;
+            const compressedSize = largeItem.response_buffers.gzip.length;
+            const expectedSavings = originalSize - compressedSize;
+
+            assert.strictEqual(assigner.compression_stats.gzip_savings, expectedSavings);
+            assert(expectedSavings > 0, 'Should have compression savings for repetitive content');
+        });
+
+        it('should handle invalid compression configuration gracefully', async function() {
+            // Test with invalid algorithm
+            const assigner = new Single_Control_Webpage_Server_Static_Compressed_Response_Buffers_Assigner({
+                compression: {
+                    enabled: true,
+                    algorithms: ['invalid_algorithm']
+                }
+            });
+
+            await assigner.assign(mockBundleItems);
+
+            // Should not compress anything due to invalid algorithm
+            mockBundleItems.forEach(item => {
+                assert(!item.response_buffers.gzip, 'Should not compress with invalid algorithm');
+                assert(!item.response_buffers.br, 'Should not compress with invalid algorithm');
+            });
+        });
+    });
+
+    describe('Compression Statistics', function() {
+        it('should track compression statistics accurately', async function() {
+            const assigner = new Single_Control_Webpage_Server_Static_Compressed_Response_Buffers_Assigner();
+
+            await assigner.assign(mockBundleItems);
+
+            // Verify all statistics are tracked
+            assert.strictEqual(assigner.compression_stats.total_items, 3);
+            assert.strictEqual(assigner.compression_stats.gzip_compressed, 3);
+            assert.strictEqual(assigner.compression_stats.brotli_compressed, 3);
+            assert(typeof assigner.compression_stats.gzip_savings === 'number');
+            assert(typeof assigner.compression_stats.brotli_savings === 'number');
+        });
+
+        it('should reset statistics between assign calls', async function() {
+            const assigner = new Single_Control_Webpage_Server_Static_Compressed_Response_Buffers_Assigner();
+
+            // First assign
+            await assigner.assign(mockBundleItems.slice(0, 1));
+            assert.strictEqual(assigner.compression_stats.total_items, 1);
+
+            // Second assign should add to statistics, not reset
+            await assigner.assign(mockBundleItems.slice(1, 2));
+            assert.strictEqual(assigner.compression_stats.total_items, 2);
+        });
+    });
+});