# ericksenagodinho/clut architecture

> Architecture diagram of the GitHub repository ericksenagodinho/clut, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ericksenagodinho/clut
- Repository: https://github.com/ericksenagodinho/clut

## Overview

CLUT is a single-header C unit-testing framework. Developers define tests and assertions, register them in a runner and suite, and execute them to produce pass/fail/skip summaries; hooks support setup and teardown, and output modes include default, GitHub Actions, and TAP. An optional runner_generator CLI reads test files and emits a runner that uses the CLUT API. Internal state and message-building support execution and reporting. The excerpts are partial, so the graph omits uncertain internal call details.

Main entry points: [`clut.h`](https://github.com/ericksenagodinho/clut/blob/main/clut.h) (Runner and suites), [`tools/runner_generator.c`](https://github.com/ericksenagodinho/clut/blob/main/tools/runner_generator.c) (Generator CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_framework["Test framework"]
  node_test_api["Test definitions<br/>[clut.h]"]
  node_assertions["Assertions<br/>[clut.h]"]
  node_runner_suite["Runner and suites<br/>[clut.h]"]
  node_hooks["Lifecycle hooks<br/>[clut.h]"]
  node_output["Test output<br/>[clut.h]"]
end

subgraph group_generator["Runner generator"]
  node_generator_cli["Generator CLI<br/>[runner_generator.c]"]
  node_wildcard["Wildcard expansion<br/>[runner_generator.c]"]
  node_lexer_parser["Lexer and parser<br/>[runner_generator.c]"]
  node_runner_emitter["Runner emitter<br/>[runner_generator.c]"]
end

subgraph group_internals["Execution internals"]
  node_runtime_state["Runner state<br/>[clut.h]"]
  node_message_builder["Message builder<br/>[clut.h]"]
end

node_developer(("Developer"))
node_terminal(("Terminal"))
node_test_files["Test source files"]
node_generated_runner["Generated runner"]

node_developer -->|"defines tests"| node_test_api
node_developer -->|"writes assertions"| node_assertions
node_developer -->|"registers tests"| node_runner_suite
node_test_api -->|"registers tests"| node_runner_suite
node_runner_suite -->|"runs hooks"| node_hooks
node_runner_suite -->|"runs tests"| node_assertions
node_assertions -->|"records failures"| node_runtime_state
node_assertions -->|"formats messages"| node_message_builder
node_runner_suite -->|"updates results"| node_runtime_state
node_runner_suite -->|"reports results"| node_output
node_output -->|"writes output"| node_terminal
node_developer -.->|"runs optionally"| node_generator_cli
node_generator_cli -->|"expands patterns"| node_wildcard
node_generator_cli -->|"parses files"| node_lexer_parser
node_wildcard -->|"selects files"| node_test_files
node_lexer_parser -->|"reads source"| node_test_files
node_generator_cli -->|"emits runner"| node_runner_emitter
node_runner_emitter -->|"writes code"| node_generated_runner
node_generated_runner -.->|"uses API"| node_runner_suite

click node_test_api "https://github.com/ericksenagodinho/clut/blob/main/clut.h"
click node_assertions "https://github.com/ericksenagodinho/clut/blob/main/clut.h"
click node_runner_suite "https://github.com/ericksenagodinho/clut/blob/main/clut.h"
click node_hooks "https://github.com/ericksenagodinho/clut/blob/main/clut.h"
click node_output "https://github.com/ericksenagodinho/clut/blob/main/clut.h"
click node_generator_cli "https://github.com/ericksenagodinho/clut/blob/main/tools/runner_generator.c"
click node_wildcard "https://github.com/ericksenagodinho/clut/blob/main/tools/runner_generator.c"
click node_lexer_parser "https://github.com/ericksenagodinho/clut/blob/main/tools/runner_generator.c"
click node_runner_emitter "https://github.com/ericksenagodinho/clut/blob/main/tools/runner_generator.c"
click node_runtime_state "https://github.com/ericksenagodinho/clut/blob/main/clut.h"
click node_message_builder "https://github.com/ericksenagodinho/clut/blob/main/clut.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_test_api,node_assertions,node_runner_suite,node_hooks,node_output toneBlue
class node_generator_cli,node_wildcard,node_lexer_parser,node_runner_emitter toneAmber
class node_runtime_state,node_message_builder toneMint
class node_developer,node_terminal,node_test_files,node_generated_runner toneIndigo
```

## Components

### Test framework

- [Test definitions](https://github.com/ericksenagodinho/clut/blob/main/clut.h): `clut.h`
- [Assertions](https://github.com/ericksenagodinho/clut/blob/main/clut.h): `clut.h`
- [Runner and suites](https://github.com/ericksenagodinho/clut/blob/main/clut.h): `clut.h`
- [Lifecycle hooks](https://github.com/ericksenagodinho/clut/blob/main/clut.h): `clut.h`
- [Test output](https://github.com/ericksenagodinho/clut/blob/main/clut.h): `clut.h`

### Runner generator

- [Generator CLI](https://github.com/ericksenagodinho/clut/blob/main/tools/runner_generator.c): `tools/runner_generator.c`
- [Wildcard expansion](https://github.com/ericksenagodinho/clut/blob/main/tools/runner_generator.c): `tools/runner_generator.c`
- [Lexer and parser](https://github.com/ericksenagodinho/clut/blob/main/tools/runner_generator.c): `tools/runner_generator.c`
- [Runner emitter](https://github.com/ericksenagodinho/clut/blob/main/tools/runner_generator.c): `tools/runner_generator.c`

### Execution internals

- [Runner state](https://github.com/ericksenagodinho/clut/blob/main/clut.h): `clut.h`
- [Message builder](https://github.com/ericksenagodinho/clut/blob/main/clut.h): `clut.h`

### Other components

- **Developer**
- **Terminal**
- **Test source files**
- **Generated runner**

## Connections

- Developer → Test definitions: defines tests
- Developer → Assertions: writes assertions
- Developer → Runner and suites: registers tests
- Test definitions → Runner and suites: registers tests
- Runner and suites → Lifecycle hooks: runs hooks
- Runner and suites → Assertions: runs tests
- Assertions → Runner state: records failures
- Assertions → Message builder: formats messages
- Runner and suites → Runner state: updates results
- Runner and suites → Test output: reports results
- Test output → Terminal: writes output
- Developer → Generator CLI: runs optionally
- Generator CLI → Wildcard expansion: expands patterns
- Generator CLI → Lexer and parser: parses files
- Wildcard expansion → Test source files: selects files
- Lexer and parser → Test source files: reads source
- Generator CLI → Runner emitter: emits runner
- Runner emitter → Generated runner: writes code
- Generated runner → Runner and suites: uses API