ArchUnitTS

ArchUnitTS is an architecture testing library that helps enforce architecture rules in TypeScript and JavaScript projects. It enables checking dependency directions, detecting circular dependencies, enforcing coding standards and much more - all with a simple setup and seamless pipeline integration.

The library is maintained by me (not full time) along with a small team. It has become the most popular architecture testing library for TypeScript, measured by GitHub stars.

Please note that the following features set and library comparison is incomplete, please checkout the repo on GitHub for up to date information.

Some Features

  • Detect and prevent circular dependencies
  • Enforce layer dependencies in your architecture
  • Apply naming conventions to enforce consistency
  • Measure code metrics like cohesion and lines of code
  • Define and validate custom architecture rules
  • Validate against UML diagrams
  • Works with Jest, Vitest, Jasmine, Mocha and other testing frameworks

Code Examples

Here are a few examples showing how ArchUnitTS can be used:

Checking for Circular Dependencies


            const rule = projectFiles().inFolder('src/**').should().haveNoCycles();
            await expect(rule).toPassAsync();

Enforcing Layered Architecture


            const rule = projectFiles()
                .inFolder('src/presentation/**')
                .shouldNot()
                .dependOnFiles()
                .inFolder('src/database/**');

            await expect(rule).toPassAsync();

Checking Code Metrics


            const rule = metrics().count().linesOfCode().shouldBeBelow(1000);
            await expect(rule).toPassAsync();

            // LCOM metric (lack of cohesion of methods), low = high cohesion
            const rule = metrics().lcom().lcom96b().shouldBeBelow(0.3);
            await expect(rule).toPassAsync();

Library Comparison

Here's how ArchUnitTS compares to other TypeScript architecture testing libraries:

Feature ArchUnitTS Other Solutions
API Stability ✅ Stable ⚠️ Unstable
Circular Dependency Detection ✅ Full support ❌ Limited or none
Layer Dependency Rules ✅ Advanced patterns ⚠️ Limited
File Pattern Matching ✅ Glob + Regex ❌ Basic patterns
Custom Rules ✅ Full support ❌ No
Code Metrics ✅ Comprehensive ❌ No
Empty Test Detection ✅ Fails by default ❌ No
Debug Logging ✅ Optional (configurable) ❌ No
LCOM Cohesion Analysis ✅ Multiple algorithms ❌ No
Distance Metrics ✅ Coupling & abstraction ❌ No
UML Diagram Validation ✅ Supported ❌ No
Architecture Slicing ✅ Supported ❌ No
Testing Framework Integration ✅ Universal (Jest, Vitest, Jasmine, Mocha, etc.) ⚠️ Limited
HTML Report Generation ✅ Rich dashboards ❌ No
TypeScript AST Analysis ✅ Deep analysis ⚠️ Basic
Performance Optimization ✅ Caching + parallel ❌ No
Error Messages ✅ Detailed + clickable ⚠️ Basic

Key Advantages

ArchUnitTS stands out from other TypeScript architecture testing libraries with several unique features:

  • Empty Test Protection: Automatically detects when tests "pass" because they analyzed zero files due to typos or incorrect patterns, preventing false positives.
  • Universal Testing Framework Support: Works with Jest, Vitest, Jasmine, Mocha, and any other testing framework, plus special syntax extensions for the most popular ones.
  • Advanced Logging: Comprehensive debugging support with different log levels to understand what files are analyzed and why tests pass or fail.
  • Code Metrics: Only library providing metrics like cohesion (LCOM), coupling metrics, distance from main sequence, and custom metrics for architectural insights.
  • Intelligent Error Messages: Detailed violation descriptions with clickable file paths that jump directly to issues in your IDE.
  • Custom Rules & Metrics: Define your own architectural rules and metrics tailored to your specific needs.
  • HTML Reports: Auto-generated dashboards with charts and detailed breakdowns for CI/CD integration.
  • Nx Monorepo Support: Built-in support for Nx workspaces with project graph integration and boundary enforcement.
View on GitHub Documentation