Based on test suites in your source code, generate diagrams that reveal your application specs.
npm install specchartsBased on test suites in your source code, generate diagrams that reveal your application specs.
From this spec fileβ¦
``ts
describe("sendRequest", () => {
describe("when server responds", () => {
describe("with success status", () => {
describe("when body valid JSON", () => {
it("returns parsed body", async () => {});
});
describe("when body invalid JSON", () => {
it("throws MALFORMED_RESPONSE", async () => {});
});
});
describe("with error status", () => {
describe("when error message matches known exception", () => {
it("re-throws exception", async () => {});
});
describe("when error message unknown", () => {
describe("when status 4xx", () => {
it("throws MALFORMED_REQUEST", async () => {});
});
describe("when status 5xx", () => {
it("throws INTERNAL_SERVER_ERROR", async () => {});
});
});
});
});
describe("when server does not respond", () => {
it("throws SERVER_TIMEOUT", async () => {});
});
});
`
β¦get this Mermaid flowchart:
`mermaid`
flowchart TD
N0(["sendRequest"])
N1["when server responds"]
N0 --> N1
N2["with success status"]
N1 --> N2
N3["when body valid JSON"]
N2 --> N3
N4(["returns parsed body"])
N3 --> N4
N5["when body invalid JSON"]
N2 --> N5
N6(["throws MALFORMED_RESPONSE"])
N5 --> N6
N7["with error status"]
N1 --> N7
N8["when error message matches known exception"]
N7 --> N8
N9(["re-throws exception"])
N8 --> N9
N10["when error message unknown"]
N7 --> N10
N11["when status 4xx"]
N10 --> N11
N12(["throws MALFORMED_REQUEST"])
N11 --> N12
N13["when status 5xx"]
N10 --> N13
N14(["throws INTERNAL_SERVER_ERROR"])
N13 --> N14
N15["when server does not respond"]
N0 --> N15
N16(["throws SERVER_TIMEOUT"])
N15 --> N16
Test suites tend to become less legible as they grow. At some point, you wonder where to write a new test or if a case might not be already covered. This gets worse with AI agents that contribute code you never wrote.
speccharts reads your test files (JS or TS) and generates Mermaid flowcharts that give a bird's eye view of test suites. describe blocks render as nodes, it and test blocks render as leaves.
It works especially well with deeply nested test suites, which can help to convey ramified logic.
For now, only JavaScript and TypeScript test files are supported.
Any files that use describe > it or describe > test syntax are supported.
`sh`
npx speccharts -i "src/*/.{spec,test}.{ts,tsx}" --single-output-file speccharts.md
This gathers all charts into a speccharts.md file such as this one.
`sh`
npx speccharts -i "src/*/.{spec,test}.{ts,tsx}" --multiple-output-files
This creates a Mermaid file next to each spec file:
``
src/
βββ http/
β βββ sendRequest.spec.ts
β βββ sendRequest.spec.ts.mmd β Generated
βββ services/
βββ getUser.spec.ts
βββ getUser.spec.ts.mmd β Generated
`sh`
npx speccharts -i "src/*/.{spec,test}.{ts,tsx}" --multiple-output-files --delete-existing-charts
Useful if you deleted or moved spec files since last generation.
`sh`
npx speccharts -i "src/*/.{spec,test}.{ts,tsx}"
Instead of writing all charts to a file, send Markdown content to standard output.
`sh`
npm install --save-dev speccharts
`ts
import { SpecChartsGenerator } from "speccharts";
const generator = new SpecChartsGenerator();
console.log(
await generator.generate({
inputFilePatterns: ["src/*/.spec.{ts,tsx}"],
})
);
`
describe blocks ending with a question mark render as decision nodes (rhombus-shaped).
Example spec:
`tsnull
describe("getUser", () => {
describe("is store available?", () => {
describe("no", () => {
it("returns ", async () => {});
});
describe("yes", () => {
describe("is user found?", () => {
describe("no", () => {
it("returns null", async () => {});
});
describe("yes", () => {
it("returns user", async () => {});
});
});
});
});
});
`
Resulting chart:
`mermaidnull\
flowchart TD
N0(["getUser"])
N1{"is store available?"}
N0 --> N1
N2(["returns \"])null\
N1 -- no --> N2
N3{"is user found?"}
N4(["returns \"])`
N3 -- no --> N4
N5(["returns user"])
N3 -- yes --> N5
N1 -- yes --> N3
Blocks with Jest table syntax render as a table.
Example spec:
`ts`
describe("getInitials", () => {
test.each([
["empty name", "no initials", "", ""],
["one-word name", "one initial", "John", "J"],
["two-word name", "two initials", "John Doe", "JD"],
["lowercase name", "two initials", "john doe", "JD"],
["three-word name", "three initials", "John Steve Doe", "JSD"],
["four-word name", "three initials", "John Steve Doe Barry", "JSD"],
])("%s β %s: %p β %p", (name, behavior, input, output) => {
expect(getInitials(input)).toEqual(output);
});
});
Resulting chart:
`mermaid`
flowchart TD
N0(["getInitials"])
N1("
")empty name β no initials : β one-word name β one initial : John β J two-word name β two initials : John Doe β JD lowercase name β two initials : john doe β JD three-word name β three initials : John Steve Doe β JSD four-word name β three initials : John Steve Doe Barry β JSD
N0 --> N1
Mermaid is a plain text diagram representation.
Mermaid files (typically .mmd`) can be:
- viewed on GitHub (native Mermaid rendering)
- embedded in Markdown documentation
- viewed in your IDE (install Mermaid Preview for Visual Studio Code)
- viewed on GitBook, Notion, or Confluence
- exported as images using Mermaid CLI
- documentation & onboarding: supply non-tech collaborators and new team members with visual, up-to-date specifications
- code reviews: help reviewers understand complex test suites at a glance
- testing strategy: identify imbalances between test suites
To add chart generation to a CI pipeline, see GitHub action example: push-main.yml.