feat: Add testing infrastructure and documentation

- Set up Vitest for unit testing with jsdom - Add test setup with Web Audio API and requestAnimationFrame mocks - Create initial test suites for DOM and animations modules - Add test scripts to package.json (test, test:ui, test:run, coverage) - Update CI workflow to include test execution - Create CONTRIBUTING.md with conventional commits guidelines - Create SECURITY.md with security policy - Update ESLint config to support test files - All tests passing (8/8) Co-authored-by: ZaneThePython <102631678+ZaneThePython@users.noreply.github.com>
2025-11-09 00:14:31 +00:00
parent 542d80802e
commit 7a4996c40a
10 changed files with 1426 additions and 3 deletions
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -7,7 +7,7 @@ on:
    branches: [ main ]

 jobs:
-  lint-and-build:
+  lint-test-build:
    runs-on: ubuntu-latest
    
    strategy:
@@ -33,6 +33,9 @@ jobs:
    - name: Check formatting
      run: npm run format:check
      
+    - name: Run tests
+      run: npm run test:run
+      
    - name: Build project
      run: npm run build
      
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -0,0 +1,179 @@
+# Contributing to ZanePersonal
+
+Thank you for your interest in contributing to this project! While this is primarily a personal website, contributions are welcome.
+
+## Commit Message Format
+
+This project follows the [Conventional Commits](https://www.conventionalcommits.org/) specification for commit messages.
+
+### Format
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+### Types
+
+- **feat**: A new feature
+- **fix**: A bug fix
+- **docs**: Documentation changes
+- **style**: Code style changes (formatting, missing semi-colons, etc.)
+- **refactor**: Code refactoring without changing functionality
+- **perf**: Performance improvements
+- **test**: Adding or updating tests
+- **build**: Changes to build system or dependencies
+- **ci**: Changes to CI configuration
+- **chore**: Other changes that don't modify src or test files
+
+### Examples
+
+```
+feat(effects): add new particle collision detection
+
+fix(animations): resolve timing issue with typewriter effect
+
+docs(readme): update installation instructions
+
+style(css): apply consistent naming convention
+
+refactor(modules): extract sound utilities to separate module
+
+perf(effects): optimize particle rendering loop
+
+test(interactions): add unit tests for ripple effect
+
+build(vite): update build configuration for better tree-shaking
+
+ci(github-actions): add accessibility testing workflow
+```
+
+## Development Workflow
+
+1. **Fork the repository** (if you're an external contributor)
+
+2. **Clone your fork**
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/ZanePersonal.git
+   cd ZanePersonal
+   ```
+
+3. **Install dependencies**
+   ```bash
+   npm install
+   ```
+
+4. **Create a feature branch**
+   ```bash
+   git checkout -b feat/your-feature-name
+   ```
+
+5. **Make your changes**
+   - Write clean, readable code
+   - Follow existing code style
+   - Add comments where necessary
+   - Update documentation if needed
+
+6. **Run quality checks**
+   ```bash
+   npm run lint        # Check for linting errors
+   npm run format      # Format code with Prettier
+   npm run build       # Ensure project builds successfully
+   ```
+
+7. **Commit your changes**
+   ```bash
+   git add .
+   git commit -m "feat(scope): your descriptive message"
+   ```
+
+8. **Push to your fork**
+   ```bash
+   git push origin feat/your-feature-name
+   ```
+
+9. **Create a Pull Request**
+   - Provide a clear description of changes
+   - Reference any related issues
+   - Ensure CI checks pass
+
+## Code Style Guidelines
+
+### JavaScript
+
+- Use ES6+ features
+- Prefer `const` over `let`, avoid `var`
+- Use arrow functions for callbacks
+- Keep functions small and focused
+- Add JSDoc comments for complex functions
+- Follow the existing modular structure
+
+### CSS
+
+- Use CSS custom properties (variables) defined in `:root`
+- Follow BEM-like naming conventions where appropriate
+- Group related properties together
+- Use meaningful class names
+- Avoid overly specific selectors
+
+### HTML
+
+- Use semantic HTML5 elements
+- Include proper ARIA labels for accessibility
+- Ensure all images have alt text
+- Maintain proper heading hierarchy
+
+## Testing
+
+While this project doesn't currently have automated tests, please ensure:
+- All features work in modern browsers (Chrome, Firefox, Safari, Edge)
+- Responsive design works on mobile, tablet, and desktop
+- No console errors or warnings
+- Accessibility features work with keyboard navigation
+
+## Performance Considerations
+
+- Keep total bundle size under 150KB (compressed)
+- Optimize images before adding them
+- Minimize use of heavy libraries
+- Test animations on lower-end devices
+- Use lazy loading where appropriate
+
+## Accessibility Standards
+
+- Maintain WCAG 2.1 Level AA compliance
+- Test with screen readers
+- Ensure keyboard navigation works
+- Provide sufficient color contrast
+- Include focus indicators on interactive elements
+
+## Pull Request Checklist
+
+Before submitting a PR, ensure:
+
+- [ ] Code follows the project's style guidelines
+- [ ] All linting checks pass (`npm run lint`)
+- [ ] Code is properly formatted (`npm run format`)
+- [ ] Project builds successfully (`npm run build`)
+- [ ] Changes are tested in multiple browsers
+- [ ] Documentation is updated if needed
+- [ ] Commit messages follow conventional commits format
+- [ ] PR description clearly explains the changes
+
+## Questions or Issues?
+
+Feel free to:
+- Open an issue for bugs or feature requests
+- Start a discussion for questions
+- Email [contact@zane.org](mailto:contact@zane.org)
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.
+
+---
+
+Thank you for contributing! 🎉
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -0,0 +1,71 @@
+# Security Policy
+
+## Supported Versions
+
+This is a personal website project. The latest version on the `main` branch is always supported.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| Latest  | :white_check_mark: |
+| Older   | :x:                |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in this project, please report it responsibly:
+
+### Email
+Send details to [contact@zane.org](mailto:contact@zane.org) with:
+- Description of the vulnerability
+- Steps to reproduce
+- Potential impact
+- Suggested fix (if any)
+
+### What to Expect
+- **Response time**: Within 48 hours
+- **Updates**: Regular communication about the issue
+- **Fix timeline**: Depends on severity and complexity
+- **Disclosure**: Coordinated disclosure after fix is deployed
+
+### Please Do Not
+- Create public issues for security vulnerabilities
+- Exploit vulnerabilities beyond proof-of-concept
+- Access data that doesn't belong to you
+- Perform DoS attacks
+
+## Security Measures
+
+This project implements several security best practices:
+
+### Code Security
+- **Input Sanitization**: All user inputs are sanitized (minimal as site is static)
+- **Dependencies**: Regular security audits via `npm audit`
+- **Linting**: ESLint configured to catch common security issues
+- **CSP Ready**: Content Security Policy headers can be added by hosting provider
+
+### Build Security
+- **Dependency Scanning**: GitHub Dependabot enabled
+- **Automated Updates**: Security patches applied automatically
+- **CI/CD**: All code passes linting and build checks
+
+### Best Practices
+- No sensitive data in repository
+- No API keys or credentials in code
+- HTTPS enforced on live site
+- Regular dependency updates
+- Minimal external dependencies
+
+## Known Limitations
+
+As a static personal website:
+- No backend or database
+- No user authentication
+- No data collection or storage
+- Minimal attack surface
+
+## Security Updates
+
+Security fixes are released as soon as possible after discovery. Check the [CHANGELOG](CHANGELOG.md) for security-related updates.
+
+---
+
+*Last updated: November 2024*
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -22,6 +22,7 @@ export default [
        setTimeout: 'readonly',
        setInterval: 'readonly',
        clearInterval: 'readonly',
+        clearTimeout: 'readonly',
        IntersectionObserver: 'readonly',
        __dirname: 'readonly',
      },
@@ -33,6 +34,19 @@ export default [
      'no-var': 'warn',
    },
  },
+  {
+    files: ['tests/**/*.js'],
+    languageOptions: {
+      globals: {
+        global: 'writable',
+        beforeEach: 'readonly',
+        describe: 'readonly',
+        it: 'readonly',
+        expect: 'readonly',
+        vi: 'readonly',
+      },
+    },
+  },
  {
    ignores: [
      'node_modules/**',
--- a/package-lock.json
+++ b/package-lock.json
--- a/package.json
+++ b/package.json
@@ -7,6 +7,10 @@
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:run": "vitest run",
+    "coverage": "vitest run --coverage",
    "lint": "eslint . --ext .js,.html",
    "lint:fix": "eslint . --ext .js,.html --fix",
    "format": "prettier --write \"**/*.{js,html,css,json,md}\"",
@@ -28,14 +32,17 @@
  },
  "homepage": "https://zane.org",
  "devDependencies": {
+    "@vitest/ui": "^4.0.8",
    "eslint": "^9.39.1",
    "eslint-config-prettier": "^10.1.8",
    "eslint-plugin-html": "^8.1.3",
    "imagemin": "^9.0.1",
    "imagemin-mozjpeg": "^10.0.0",
    "imagemin-pngquant": "^10.0.0",
+    "jsdom": "^27.1.0",
    "prettier": "^3.6.2",
    "terser": "^5.44.1",
-    "vite": "^7.2.2"
+    "vite": "^7.2.2",
+    "vitest": "^4.0.8"
  }
 }
--- a/tests/animations.test.js
+++ b/tests/animations.test.js
@@ -0,0 +1,40 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { typeWriter } from '../assets/js/modules/animations.js';
+
+describe('Animations Module', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  describe('typeWriter', () => {
+    it('should type text character by character', async () => {
+      const element = document.createElement('div');
+      document.body.appendChild(element);
+
+      const text = 'Hello';
+      typeWriter(element, text, 50);
+
+      // Wait for first setTimeout to execute
+      await vi.runAllTimersAsync();
+
+      // Complete text should be shown
+      expect(element.innerHTML).toBe('Hello');
+    });
+
+    it('should handle null element gracefully', () => {
+      expect(() => {
+        typeWriter(null, 'text', 50);
+      }).not.toThrow();
+    });
+
+    it('should handle empty text', () => {
+      const element = document.createElement('div');
+      document.body.appendChild(element);
+
+      typeWriter(element, '', 50);
+      vi.advanceTimersByTime(100);
+
+      expect(element.innerHTML).toBe('');
+    });
+  });
+});
--- a/tests/dom.test.js
+++ b/tests/dom.test.js
@@ -0,0 +1,69 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { DOM, getNavElements, getMainElements } from '../assets/js/modules/dom.js';
+
+describe('DOM Module', () => {
+  beforeEach(() => {
+    // Setup basic HTML structure
+    document.body.innerHTML = `
+      <div class="container">
+        <div class="avatar">Avatar</div>
+        <h1 class="brand-name">ZaneDev</h1>
+        <p class="tagline">Tagline</p>
+        <nav class="navigation">
+          <a href="#" class="nav-button">Button 1</a>
+          <a href="#" class="nav-button">Button 2</a>
+        </nav>
+      </div>
+    `;
+  });
+
+  describe('DOM utility', () => {
+    it('should cache and retrieve elements', () => {
+      const avatar = DOM.get('.avatar');
+      expect(avatar).toBeTruthy();
+      expect(avatar.textContent).toBe('Avatar');
+
+      // Should return cached version on second call
+      const avatarAgain = DOM.get('.avatar');
+      expect(avatarAgain).toBe(avatar);
+    });
+
+    it('should get all elements matching selector', () => {
+      const buttons = DOM.getAll('.nav-button');
+      expect(buttons).toHaveLength(2);
+    });
+
+    it('should clear cache', () => {
+      DOM.get('.avatar');
+      expect(Object.keys(DOM.cache).length).toBeGreaterThan(0);
+
+      DOM.clearCache();
+      expect(Object.keys(DOM.cache).length).toBe(0);
+    });
+  });
+
+  describe('getMainElements', () => {
+    it('should return main UI elements', () => {
+      const elements = getMainElements();
+
+      expect(elements.avatar).toBeTruthy();
+      expect(elements.brandName).toBeTruthy();
+      expect(elements.tagline).toBeTruthy();
+    });
+  });
+
+  describe('getNavElements', () => {
+    it('should return navigation elements', () => {
+      // Add required elements for navigation
+      document.body.innerHTML += `
+        <div class="content-section"></div>
+        <button class="close-button">Close</button>
+      `;
+
+      const elements = getNavElements();
+
+      expect(elements.navButtons).toBeTruthy();
+      expect(elements.navButtons.length).toBeGreaterThan(0);
+    });
+  });
+});
--- a/tests/setup.js
+++ b/tests/setup.js
@@ -0,0 +1,34 @@
+// Test setup file
+import { beforeEach, vi } from 'vitest';
+
+// Mock Web Audio API
+global.AudioContext = vi.fn().mockImplementation(() => ({
+  createOscillator: vi.fn().mockReturnValue({
+    connect: vi.fn(),
+    frequency: {
+      setValueAtTime: vi.fn(),
+      exponentialRampToValueAtTime: vi.fn(),
+    },
+    start: vi.fn(),
+    stop: vi.fn(),
+  }),
+  createGain: vi.fn().mockReturnValue({
+    connect: vi.fn(),
+    gain: {
+      setValueAtTime: vi.fn(),
+      exponentialRampToValueAtTime: vi.fn(),
+    },
+  }),
+  destination: {},
+  currentTime: 0,
+}));
+
+// Mock requestAnimationFrame
+global.requestAnimationFrame = vi.fn((callback) => setTimeout(callback, 16));
+global.cancelAnimationFrame = vi.fn(clearTimeout);
+
+// Reset DOM before each test
+beforeEach(() => {
+  document.body.innerHTML = '';
+  document.head.innerHTML = '';
+});
--- a/vite.config.js
+++ b/vite.config.js
@@ -37,4 +37,13 @@ export default defineConfig({
    port: 5173,
    open: true,
  },
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    setupFiles: './tests/setup.js',
+    coverage: {
+      reporter: ['text', 'html'],
+      exclude: ['node_modules/', 'dist/', 'tests/'],
+    },
+  },
 });