gorkin 🚀

A "Zero-Intrusion" Living Documentation & BDD Test Engine designed specifically for Go.

gorkin instantly transforms dry Gherkin (.feature) test scenarios into a modern, interactive VitePress-powered Living Documentation site. It allows non-technical team members (PMs, designers) to easily read business acceptance criteria, while enabling developers to click "Run" directly on the web page to trigger underlying Ginkgo automated tests in real-time!

✨ Key Features

• 📖 True Living Documentation: Automatically parses .feature files to generate a static documentation site with nested multi-level sidebars.
• 🎮 Dynamic Web Execution: Every test scenario has a "Run" button. With a single click, it automatically locates and executes the corresponding Ginkgo test across your Go modules.
• 🛡️ Physical Zero-Intrusion: Fully configuration-driven. All cache and JSON reports generated during execution are isolated within the tool's own directory. It will never pollute your Go codebase with extraneous files.
• 🔗 Loose Coupling Protocol: Supports custom regular expressions for tag association (e.g., @JIRA-123), requiring zero changes to your existing agile workflow.

📦 Installation & Initialization

We recommend installing it locally as a development dependency in your project.

Run this in your Go project root:

# 1. Install dependency
npm install gorkin --save-dev

# 2. Scaffold via 1-click init
npx @zhengfaning/gorkin init

Running init will safely generate the following structure in your current directory (it will skip existing files to prevent overwriting):

• gorkin/gorkin.config.js (Core configuration file)
• features/hello.feature (Demo Gherkin scenario)
• hello_test.go (Demo Ginkgo association code)

⚙️ Core Configuration

After initialization, all the magic is driven by gorkin/gorkin.config.js. You can adjust it based on your team's directory structure:

/** @type {import('gorkin/src/config/types').BddDocsConfig} */
const config = {
  // Directory of your .feature files (relative to this config file)
  featuresDir: '../features',

  // Directory of your Go modules (used to recursively discover go.mod)
  // Supports arrays for microservice architectures: ['../api-server', '../engine']
  modulesDir: ['../'],

  // Directory for isolated JSON reports generated by Ginkgo (ensuring zero intrusion)
  reportsDir: './.reports',

  // [Crucial] Association Protocol: Regex used to match Gherkin and Ginkgo tags
  // The default pattern matches tags like @HELLO_001, @ENGINE_999
  tagPattern: /^[A-Z0-9]+_\d{3}$/,

  // Site metadata
  title: 'My BDD Living Docs',
  description: 'Powered by gorkin',
}

module.exports = config;

🤝 Association Protocol: Bridging Docs and Code

To make the "Run" button on the webpage functional, you only need to respect one contract: Keep the Tag IDs consistent.

Step 1: Tagging in Gherkin (.feature) Above your scenario, use a tag that matches your tagPattern regex (prefixed with @):

@HELLO_001
Scenario: Simple Math Calculation
  Given I have a calculator
  When I add 2 and 2
  Then the result must be 4

Step 2: Registering Label in Ginkgo (_test.go) On the Go side, use Ginkgo's Label decorator to mount the exact same ID (without the @):

var _ = Describe("Math Calculation", Label("HELLO_001"), func() {
    It("Simple math calculation", func() {
        Expect(2 + 2).To(Equal(4))
    })
})

That's it! The tool will automatically scan and align data from both sides upon startup.

🛠️ Command Line Interface

Within your project, you can control the tool's entire lifecycle using npx @zhengfaning/gorkin [command]:

| Command | Description | | :--- | :--- | | npx @zhengfaning/gorkin init | Smartly scaffolds config templates & demo code (includes anti-overwrite safety locks). | | npx @zhengfaning/gorkin dev | Starts the local dev server. Supports Markdown hot-reloading for real-time preview. | | npx @zhengfaning/gorkin build| Builds the production-ready static site (output generated in .vitepress/dist). | | npx @zhengfaning/gorkin serve| Locally previews the built production static site. | | npx @zhengfaning/gorkin test | Offline test command. Scans Go modules and executes a full suite of tests to generate linked reports. |

💡 Pro Tip: You can add these commands to your package.json's scripts for quick launching, e.g., via npm run docs:dev.

🏗️ Requirements

• Node.js: v18+ (Required for VitePress rendering and JS probes)
• Go: 1.20+ with go available in your system PATH
• Ginkgo: v2 (Strictly depends on Ginkgo v2's JSON report format)