How mgrafl/shellspec-ext-invocation works
Project type and purpose
• This is an open‐source ShellSpec extension, implemented in Bash, that provides a “capture_invocation” feature for mocking and verifying command/function invocations in ShellSpec test suites.
• It is not a full‐stack application but a plugin/library for ShellSpec with both unit tests and integration tests (including a Docker‐based test harness).
File structure
• lib/extension/invocation/… : the core extension code (capture_invocation function, helper scripts, matcher definitions).
• shellspec-ext-invocation : wrapper CLI script that sets up ShellSpec with the extension.
• spec/… and integration/spec/… : Bash test cases (unit and integration).
• Dockerfile & GitHub workflows: build/test pipelines and Docker images.
• CONFIG & CI files (.shellspec, Dockerfile, .github/workflows) : define test runners and Docker image publication.
README for architecture insights
• The extension consists of:
• capture_invocation function (stores command name + args)
• ShellSpec subjects (“number of mocks”, “mock”/“invocation”)
• ShellSpec matcher (“have received arguments”)
• Usage sections show how the extension is loaded into the ShellSpec CLI, and how tests invoke it under Docker.
Main components
A. ShellSpec CLI (the test runner core)
B. Extension Loader (shellspec-ext-invocation wrapper or --load-path flag)
C. capture_invocation module (Bash functions under lib/extension/invocation)
D. invocation helper scripts (capture_invocation_helper.sh, have_received_arguments.sh, etc.)
E. Test Suites
• Unit tests (spec/)
• Integration tests (integration/spec/)
F. Docker Image
• mgrafl/shellspec-ext-invocation (standard + “docker” variant with Docker-in-Docker)
G. CI/CD Pipeline (GitHub Actions workflows)
Relationships and data flows
1. Developer writes tests in spec/ or integration/spec/ that call ShellSpec with the extension loaded.
2. shellspec-ext-invocation (or shellspec CLI with --load-path) loads the capture_invocation scripts.
3. When tests run, capture_invocation intercepts mocked commands/functions and logs their names + args into an internal array/state.
4. Test matchers (number of mocks, have received arguments) query that stored state to pass/fail assertions.
5. Docker image provides a reproducible environment: it bundles shellspec core + extension code + helper scripts.
6. GitHub Actions orchestrates building the Docker image, running unit tests, and publishing the Docker image.
Architectural patterns and design principles
• Plugin architecture: the extension attaches to ShellSpec via a load path, registering new subjects and matchers.
• Separation of concerns:
• Core extension logic (capture_invocation functions)
• Test definitions (spec files)
• Packaging and CI/CD (Dockerfile, workflows)
• Unix philosophy: small shell scripts each doing one thing, composed via load paths and standard ShellSpec hooks.
b. Inside it, nest a “Load Extension” element that imports lib/extension/invocation/*.sh.
c. Capture_invocation functions writing to an “Invocation Store” (in-memory Bash array).
d. Matcher functions reading from the “Invocation Store.”
f. Below, place “Docker Image” as the runtime container that houses ShellSpec + extension.
g. Above, show “CI/CD (GitHub Actions)” orchestrating the Docker build and test runs.
Essential elements
• Clear component labels (CLI, Extension, Tests, Docker, CI/CD)
• Annotations of key scripts or file groups