3D Sort

A 3D sorting algorithm Progressive Web App (PWA).

Try it out »

Getting Started · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
3. How to Test
   • Running Tests
   • Test Coverage
4. CI/CD Pipeline
   • Automated Testing
   • Build Validation
   • Quality Gates
5. Contributing
6. Contact

About The Project

This project helps users understand how sorting algorithms work in a visual and interactive way. It supports offline usage thanks to PWA technology and lets users control the speed of animations to match their learning pace.

Features

• Offline and app support (PWA)
• Choose from multiple sorting algorithms
• Adjustable animation speed
• Mobile responsive

Algorithms Implemented

• Bubble Sort
• Selection Sort
• Insertion Sort
• Merge Sort
• Quick Sort
• Heap Sort

Built With

• React
• TypeScript
• Three.js
• @react-three/fiber by Poimandres
• Vite
• Vite PWA Plugin
• React Icons

Getting Started

npm install

Installs all necessary dependencies.

npm run dev

Starts the app in development mode.

The page will automatically reload if you make edits.

How to Test

This project includes a comprehensive test suite with 82+ tests covering sorting algorithm correctness, edge cases, and visualization data validation.

Running Tests

# Run tests in watch mode (interactive)
npm run test

# Run tests once and exit
npm run test:run

# Run tests with UI (browser-based test runner)
npm run test:ui

Test Coverage

The test suite includes:

Sorting Algorithm Tests (48 tests)

• Correctness validation for all 6 algorithms
• Edge cases: empty arrays, single elements, sorted/reverse sorted data, duplicates, negative numbers
• Generator behavior: ensures proper step-by-step data for 3D visualization

Utility Function Tests (15 tests)

• findMaxValue: maximum value detection
• shuffle: array randomization with element preservation

Visualization Data Tests (4 tests)

• Array length consistency throughout sorting
• Element preservation (no data loss)
• Valid index bounds checking
• Proper animation state indicators

Advanced Edge Cases (6 tests)

• Large arrays (100+ elements)
• Extreme values (MAX_SAFE_INTEGER/MIN_SAFE_INTEGER)
• Floating-point number handling
• Two-element arrays
• Arrays with identical elements

All tests ensure both mathematical correctness and proper 3D visualization data generation for the sorting animations.

CI/CD Pipeline

This project uses GitHub Actions for continuous integration and deployment with comprehensive testing and quality assurance:

Automated Testing

• Test Workflow (test.yml): Runs on every push and pull request
  • Multi-Node Testing: Tests against Node.js 18.x and 20.x
  • Comprehensive Test Suite: Runs the full test suite with 82+ tests
  • Coverage Reports: Generates and uploads test coverage to Codecov
  • TypeScript Validation: Ensures code compiles without errors
  • Separate Jobs: test, lint, and test-coverage for parallel execution

Build Validation

• Build Workflow (build.yml): Validates application build and performance
  • Build Verification: Ensures the application builds successfully
  • Lighthouse CI: Performance, accessibility, and PWA testing on pull requests
  • Artifact Storage: Saves build outputs and test results for review
  • Performance Thresholds:
    • Performance: ≥80% (warning)
    • Accessibility: ≥90% (error)
    • Best Practices: ≥80% (warning)
    • SEO: ≥80% (warning)
    • PWA: ≥80% (warning)

Quality Gates

• ✅ All tests must pass before merging (82+ tests across all algorithms)
• ✅ TypeScript compilation must succeed
• ✅ Build must complete successfully
• ✅ Lighthouse performance thresholds must be met
• ✅ Code coverage tracking via Codecov integration

Workflows

.github/workflows/
├── test.yml        # Comprehensive test suite with multi-node testing
└── build.yml       # Build validation and Lighthouse performance testing

Key Features:

• npm-based: All workflows use npm with proper package-lock.json caching
• Parallel Execution: Tests run on multiple Node.js versions simultaneously
• Performance Monitoring: Lighthouse CI ensures optimal user experience
• Coverage Tracking: Codecov integration with detailed test coverage reports
• Artifact Management: Build outputs and test results preserved for debugging

Contributing

Contributions make the open source community amazing. Any contributions you make are greatly appreciated.

1. Fork the repository
2. Create your feature branch (git checkout -b feature)
3. Commit your changes (git commit -m 'Add new feature')
4. Push to the branch (git push origin feature)
5. Open a Pull Request

Contact

• Email: marcelorissette15@gmail.com
• Project Link: https://github.com/marcelo-schreiber/3d-sort

Made with <3 by Marcelo Schreiber