# rspec/rspec-rails architecture

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

- Interactive diagram: https://gitdiagram.com/rspec/rspec-rails
- Repository: https://github.com/rspec/rspec-rails

## Overview

##### Project type and purpose
- This is an open-source Ruby gem (rspec-rails) that integrates RSpec into Ruby on Rails.
- It provides testing DSL extensions, Rails-specific example groups, generators, matchers, tasks, and documentation.

##### File structure
- Top-level:
- lib/rspec-rails – the core integration modules (configuration, example groups, matchers, extensions, tasks)
- lib/generators/rspec – the set of Rails generators for specs (model, controller, feature, etc.)
- example_app_generator – a set of sample Rails apps used to test generators end-to-end
- features/ – Cucumber feature specs describing behaviors
- spec/ – RSpec unit/spec tests for the gem itself
- yard/ – YARD documentation templates
- .github/, script/, ci files – CI/CD workflows, build scripts

##### README for additional insights
- Describes that the gem “drops in” as an alternative test framework to Minitest.
- Highlights DSL basics, supported Rails versions, installation, generators, spec types, and matchers.
- Points to example code under example_app_generator and detailed Cucumber features.

##### Main components
a. Core Integration Module
– lib/rspec-rails.rb & lib/rspec/rails/**/*.rb
– Configuration, railtie hooks, example group classes, Rails adapters
b. Generators Subsystem
– lib/generators/rspec/**
– Templates, generator classes, integrate with Rails’ generator API
c. Example Apps & Cucumber Features
– example_app_generator/* and features/*.feature
– Drive end-to-end tests of generator behavior and feature specs
d. Test Suite
– spec/* – unit/spec tests verifying core behavior
– features/* – acceptance tests for higher-level behaviors
e. Documentation
– yard/template – generates HTML docs with YARD
f. CI/CD Pipelines
– .github/workflows/ci.yml, appveyor.yml, script/* – build, lint, test, deploy tasks

##### Relationships and interactions
- The Core Integration Module “hooks” into Rails at initialization via a Railtie
- The Generators Subsystem uses Rails’ generator API to scaffold spec files in user apps
- Example Apps feed into both RSpec unit tests and Cucumber features to verify real-world usage
- The Test Suite exercises both core modules and generators (unit tests) and end-to-end scenarios (features)
- Documentation is generated from code comments via YARD, using yard/template

##### Architectural patterns and design principles
- Plugin / Extension Pattern: uses Railtie to inject behavior
- Code Generation Pattern: templated generators for boilerplate
- Layered Testing Strategy: unit tests (spec/), acceptance tests (features/), and example applications (example_app_generator/)
- Convention Over Configuration: follow Rails filesystem conventions for spec types

##### Relevant technologies, frameworks, and libraries
- Ruby, RubyGems
- Ruby on Rails (Railtie, generators API)
- RSpec core (rspec-core, rspec-expectations)
- Cucumber for features
- YARD for documentation
- GitHub Actions / AppVeyor for CI

##### Elements
- Clear labels: Core Integration, Generators, Test Suite (unit/spec), Acceptance Tests (features), Example Apps, Documentation, CI/CD
- Core modules (red)
- Generators (blue)
- Tests (green)
- Docs (yellow)
- CI/CD (gray)

## Diagram (Mermaid)

```mermaid
flowchart TD
    Repo["Repository"]:::external
    Rails["Ruby on Rails"]:::external

    subgraph "Core Integration Module"
        CoreEntry["rspec-rails.rb"]:::core
        CoreDir["lib/rspec/rails/"]:::core
    end

    subgraph "Generators Subsystem"
        GenEntry["lib/generators/rspec.rb"]:::gen
        GenDir["lib/generators/rspec/"]:::gen
    end

    subgraph "Example Apps & Cucumber Features"
        ExampleApp["example_app_generator/"]:::example
        CucumberFeatures["features/"]:::test
    end

    subgraph "Test Suite"
        UnitTests["spec/"]:::test
        GenSpecs["spec/generators/rspec/"]:::test
        AcceptanceTests["features/"]:::test
    end

    Doc["yard/template/"]:::docs

    subgraph "CI/CD Pipelines"
        GHActions[".github/workflows/ci.yml"]:::ci
        AppVeyor["appveyor.yml"]:::ci
        Scripts["script/"]:::ci
    end

    Repo -->|"CI build"| GHActions
    Repo -->|"CI build"| AppVeyor
    Repo -->|"CI build"| Scripts

    Rails -->|"initializes"| CoreEntry
    Rails -->|"initializes"| CoreDir

    Rails -->|"generate command"| GenEntry
    Rails -->|"generate command"| GenDir

    ExampleApp -->|"uses generators"| GenEntry

    CoreEntry -->|"unit tests"| UnitTests
    CoreDir -->|"unit tests"| UnitTests

    GenEntry -->|"generator tests"| GenSpecs
    GenDir -->|"generator tests"| GenSpecs

    AcceptanceTests -->|"acceptance tests"| CoreEntry
    AcceptanceTests -->|"acceptance tests"| GenEntry

    CoreEntry -->|"generate docs"| Doc

    click CoreEntry "https://github.com/rspec/rspec-rails/blob/main/lib/rspec-rails.rb"
    click CoreDir "https://github.com/rspec/rspec-rails/tree/main/lib/rspec/rails/"
    click GenEntry "https://github.com/rspec/rspec-rails/blob/main/lib/generators/rspec.rb"
    click GenDir "https://github.com/rspec/rspec-rails/tree/main/lib/generators/rspec/"
    click ExampleApp "https://github.com/rspec/rspec-rails/tree/main/example_app_generator/"
    click CucumberFeatures "https://github.com/rspec/rspec-rails/tree/main/features/"
    click UnitTests "https://github.com/rspec/rspec-rails/tree/main/spec/"
    click GenSpecs "https://github.com/rspec/rspec-rails/tree/main/spec/generators/rspec/"
    click AcceptanceTests "https://github.com/rspec/rspec-rails/tree/main/features/"
    click Doc "https://github.com/rspec/rspec-rails/tree/main/yard/template/"
    click GHActions "https://github.com/rspec/rspec-rails/blob/main/.github/workflows/ci.yml"
    click AppVeyor "https://github.com/rspec/rspec-rails/blob/main/appveyor.yml"
    click Scripts "https://github.com/rspec/rspec-rails/tree/main/script/"

    classDef core fill:#fbb,stroke:#f00,color:#000
    classDef gen fill:#bbf,stroke:#00f,color:#000
    classDef test fill:#bfb,stroke:#0f0,color:#000
    classDef docs fill:#ffeb99,stroke:#cc0,color:#000
    classDef ci fill:#ddd,stroke:#999,color:#000
    classDef external fill:#eee,stroke:#aaa,color:#000
    classDef example fill:#eef,stroke:#99f,color:#000
```
