# quick/nimble architecture

> Architecture diagram of the GitHub repository quick/nimble, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/quick/nimble
- Repository: https://github.com/quick/nimble

## Overview

##### Project Type and Purpose
- Nimble is a testing framework for Swift (and Objective-C), meant to enable expressive expectations and matchers within test suites.
- The README conveys that it can be used standalone or paired with its sister project, Quick. It also supports multiple dependency managers (Swift Package Manager, CocoaPods, Carthage, Git Submodules).

##### File Structure
- CI/Integration: The .github directory holds many GitHub Actions workflows (for Xcode, SwiftPM, documentation, linting, releases, etc.) which indicates rigorous continuous integration and quality assurance.
- Configuration and Build Files: Files like Dockerfile.test, Gemfile, Package.swift, and various project files (Nimble.xcodeproj) indicate that the project supports multi-platform builds and dependency management.
- Sources: The heart of the framework is in the Sources/Nimble folder. Here you have:
- Core DSL definitions for test expectations (e.g., DSL.swift, Expectation.swift, Expression.swift)
- A large set of matchers (in Sources/Nimble/Matchers) such as BeCloseTo, BeEmpty, etc.
- Adapters that connect Nimble with different testing environments (XCTest, Objective-C) and asynchronous testing helpers.
- Utilities and Async-related support for ensuring that asynchronous expectations are handled properly.
- Objective-C Interoperability: The Sources/NimbleObjectiveC folder contains Objective-C code and headers to expose Nimble’s functionality to ObjC tests.
- Documentation: Located under Sources/Nimble/Nimble.docc, which provides structured documentation content.
- Testing: The Tests directory includes both Swift and Objective-C test cases for verifying matchers, DSL behavior, and overall functionality.

##### Main Components
a. Core Library:
- Represents the central Nimble components (DSL, Expectation, Expression).
- Internal matching system with subcomponents for different matchers (in the Matchers subdirectory).
- A utility module for async handling (AsyncExpression, AsyncAwait, etc.).
b. Adapters:
c. Objective-C Support:
- Separate module that includes the Objective-C bridging code (Sources/NimbleObjectiveC and its include files) to show interoperability.
d. Testing Infrastructure:
- Tests directory separately to indicate the testing of various components.
- Integration with CI workflows (as found in .github/workflows) that run tests, manage documentation builds, linting, and release procedures.
e. Integration Points:
- Support for different dependency management systems (Swift Package Manager, CocoaPods, Carthage, Git Submodules).
- Possibly include external consumers such as integration with Quick (referenced in the README).

- External integration flows from dependency managers (like SPM, CocoaPods, Carthage) to the Nimble core library, highlighting installation paths and runtime linking with test targets.

##### Important Architectural Patterns and Technologies
- Modular structure that separates core functionality from adapters and matchers. This enables plug-and-play extensibility and makes it easier to maintain cross-language support (Swift and Objective-C).
- Use of DSLs for test expectation syntax, making test cases more readable.
- Asynchronous testing support as a critical pattern given modern concurrency features in Swift.
- Mention the integration of continuous integration and delivery pipelines (GitHub Actions workflows) and their role in automated quality checks.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Integration"
        A["Dependency Management & Project Configuration"]:::dependency
        B["Continuous Integration & Build Tools"]:::ci
    end

    subgraph "Core Library"
        C["Core DSL & Expectation Engine"]:::core
        D["Matchers Module"]:::module
        E["Adapters Layer (XCTest/Swift/Non-Objective-C)"]:::adapter
        F["Objective-C Support"]:::adapter
        G["Asynchronous Utilities & Extensions"]:::module
    end

    H["Testing Infrastructure"]:::test

    A --> C
    C --> D
    D --> C
    C --> E
    C --> F
    C --> G
    C --> H
    E --> H
    B --> H

    classDef core fill:#bbf,stroke:#00d,stroke-width:2px;
    classDef module fill:#dfd,stroke:#080,stroke-width:2px;
    classDef adapter fill:#ffd,stroke:#cc0,stroke-width:2px;
    classDef ci fill:#efe,stroke:#080,stroke-width:2px;
    classDef dependency fill:#fed,stroke:#a00,stroke-width:2px;
    classDef test fill:#eee,stroke:#333,stroke-width:2px;

    click C "https://github.com/quick/nimble/tree/main/Sources/Nimble"
    click D "https://github.com/quick/nimble/tree/main/Sources/Nimble/Matchers"
    click E "https://github.com/quick/nimble/tree/main/Sources/Nimble/Adapters"
    click F "https://github.com/quick/nimble/tree/main/Sources/NimbleObjectiveC"
    click G "https://github.com/quick/nimble/blob/main/Sources/Nimble/AsyncExpression.swift"
    click B "https://github.com/quick/nimble/tree/main/.github/workflows"
    click A "https://github.com/quick/nimble/blob/main/Package.swift"
    click H "https://github.com/quick/nimble/tree/main/Tests"
```
