Turn your automated tests into living product documentation — without the BDD (behavior-driven development) overhead.

Testing isn't just about catching bugs. When done correctly, automated tests serve critical functions:

1. Verifying Behavior: Ensuring the system does exactly what the business intended.
2. Enabling Refactoring: Providing the safety net needed to improve code without breaking functionality.
3. Living Documentation: Acting as the ultimate source of truth for how the system actually works.
4. Increased agility: See Philosophy & Culture more:
   • Waste Elimination
   • Iterating with Fast Validated Feedback
   • Value Amplification

The conventional approach to BDD (like Cucumber or Gherkin) tries to solve this but often introduces Waste and is suboptimal at solving the above. By forcing you to maintain separate feature files and "glue code," it creates:

• Complexity: You spend more time managing the framework than testing the product.
• Fragility: Tests break because of text changes, not logic changes.
• Documentation Rot: Feature files quickly drift from the actual code behavior.

Flow BDD is the most productive way to implement Behavior Driven Development by turning the process on its head. Instead of writing static feature files first, you write clean, best-practice code first.

Flow BDD then automatically generates:

• Interactive Feature Files: Documentation that is always in sync with your code.
• UML Diagrams: Visualizing downstream interactions and data flows (HTTP headers/bodies).
• Living UI: A generated dashboard with buttons to re-run tests and modify parameters on the fly.

Focus on testing the behavior with best practices. Automate the documentation.

@ExtendWith(FlowBdd.class)
public class DevTeamSimulatorTest extends BaseTest {

    @Override
    public void doc() {
        featureNotes("Dev Team Simulator: Verify developer actions endpoints – the world's most advanced team simulator... that only masters drinking coffee and accumulating tech debt, with predetermined biased outputs ☕🚫");
    }

    @Test
    void developerDrinksCoffee_getsPerformanceBoost() throws Exception {
        givenDeveloperIs("Alice");
        whenDeveloperDrinksCoffee();
        thenDeveloperGetsPerformanceBoost();
    }

    @Test
    void developerDoesNoTesting_getsTechDept() throws Exception {
        givenDeveloperIs("Bob");
        whenDeveloperDoesNoTesting();
        thenDeveloperGetsTechDept();
    }
}

Flow BDD uses a process called Wordify to turn your clean Java code into human-readable documentation.

For example, a test method like whenDeveloperDrinksCoffee() is automatically tokenized to:
When developer drinks coffee.

It gives you the freedom to write tests in the way you want, without the "Gherkin tax." There is a simple API to:

• Add Notes: Use featureNotes() to set the scene (e.g., explaining that your simulator only masters coffee and tech debt).
• Capture Interactions: Automatically generate Sequence Diagrams showing the flow between a User and the DevTeamSimulator.
• Inspect Data: Capture HTTP request/response headers and bodies (like the "1.21 Gigawatts of caffeine" payload).
• Interactive Control: It leverages JUnit 5 to provide a UI where you can re-run tests or even modify parameters on the fly.

By removing the "Gherkin tax" and focusing on code-first documentation, Flow BDD delivers:

• Zero Drift: Your documentation is a reflection of your code, not a separate text file that you hope someone remembered to update.
• Maintainable Tests: No regex glue layers or "step explosion." If your code compiles, your documentation is ready.
• Better Practice baked in: The framework encourages clean, builder-based test design (like our DevTeamSimulatorTest) which naturally leads to better system architecture.
• Trustworthy Specs: When a test fails, you aren't just looking at a stack trace; you're looking at a Sequence Diagram of exactly where the communication broke down.

• Living Documentation: Automatically generate HTML feature files directly from your Java or Kotlin or hopefully any JVM test code.
• Visual Flow Analysis: Integrated Mermaid.js support to capture downstream interactions and render them as UML Sequence Diagrams.
• Data Flow Capture: Capture and display full HTTP request/response payloads (headers and bodies) within the documentation.
• Fluent Test Design: Encourages the use of Type-Safe Builders, leading to more consistent state setup and more readable assertions.
• Zero Glue Layer: Eliminate the complexity of traditional BDD frameworks. No regex, no separate feature files, no "Gherkin tax."

Flow BDD is evolving. Here is what’s on the horizon:

• Interactive Test Runner – A built-in UI to re-run specific tests and modify parameters on the fly.
• Asynchronous Actions – Wrapping steps in async actions to significantly improve test execution performance.
• Intelligent Mutation Testing – Automatically validate the correctness of your scenarios by mutating steps and asserting state changes.
• Declarative JSON Builders - Generate Type-Safe builders directly from JSON schema definitions.
• Persistent Analytics – Store test results over time to query trends, irregular failures, and performance regressions

• A Tool, Not a Replacement: I use AI every day, but it’s a co-pilot, not the captain. AI can write implementation faster than us, but it doesn't always understand the intent and or optimise for code quality
• The "Coffee Gap": An AI can write a drinks-coffee endpoint in 2 seconds, but Flow BDD can tell the AI: "Hey, Alice is still sleepy, you forgot to calculate the productivity boost!" ☕️🤖
• Making Code "LLM-Readable": LLMs struggle with large, messy codebases, but they thrive on structured BDD steps and Sequence Diagrams. Flow BDD provides the high-signal context that AI needs to be actually useful.

E2E and Integration tests are not enough. They tell you if a system works, but they don't always tell you why or if it's doing the right thing at the boundary. If you are using AI to generate code, this is even more important.

Flow BDD focuses on Behavioral Assurance:

1. Unit Tests: (The "How") Logic verification.
2. TDD Test Driven Development: Drives architecture. If you write tests, you may as well write tests first! If you want better quality code, then do this. But it comes at a cost, it takes time and effort.
3. Integration Tests: (The "Connection") Validates the integration between components and external systems.
4. Flow BDD: (The "What & Why") Behavioral verification.
5. E2E Tests: (The "How") End-to-End verification, the same as a user journey. But at a cost, if there are services A, B, C; each has 10 different flows, then you have 1,000 (10x10x10) different flows to test. These are traditionally brittle and expensive to maintain; any breakage in service A would mean the rest can't be tested.

I developed VIEW MAP Communication & Culture - The core principles that serve as the fundamental building blocks of productivity and competitiveness. Traditional BDD often introduces Waste (the "Gherkin tax," fragile glue code, and documentation drift) and therefore impacts Iterating with Fast Validated Feedback and Value. Value is added by using Flow BDD that ensures we build exactly what was intended.

We believe in:

• Waste Elimination: Identify and remove non-value-adding activities.
• Iterating with Fast Validated Feedback: Develop products and services through continuous, feedback-driven iterations. This leads to shared knowledge, which is far more important than most people realize.
• Value Amplification: Focus on increasing the value delivered to customers.

Learn more here: VIEW MAP: Communication & Culture in Engineering.

Include the dependency in your build.gradle.kts:

testImplementation("io.techthinking:flowbdd:0.1.1-SNAPSHOT")

Example POM for Maven:

<groupId>io.techthinking</groupId>
<artifactId>flowbdd</artifactId>
<version>0.1.1-SNAPSHOT</version>

Annotate your test class with @FlowBdd

@ExtendWith(FlowBdd.class)
public class MyFirstFlowTest {
    @Test
    void myAwesomeScenario() {
        givenSomething();
        whenAnActionIsPerformed();
        thenTheResultIsVerified();
    }
}

Want to see it in action? The Dev Team Simulator is our hero example:

1. Clone the repo: git clone https://github.com/techthinking-io/flowbdd.git
2. Run the test:

• Run DevTeamSimulatorTest in your IDE
• ./gradlew :examples:devteam:test

3. Open the Report: Check your IDE/Terminal console. Flow BDD automatically prints a direct link to your living documentation:

   HTML Suite: file:///tmp/flowbdd/report/TEST-io.techthinking.flowbdd.examples.devteam.bdd.DevTeamSimulatorTest.html
   

Please see

• examples:bookstore
• example:cucumbers
• Run GetBookTest and or EatCucumbersTest

• Run all tests:
  • ./gradlew test
• Publish to Maven Local:
  • ./gradlew publishToMavenLocal
• To check the jar was created in maven local:
  • ls -la ~/.m2/repository/io/techthinking/flowbdd

Then use the following in your app, please check what version to use testImplementation("io.techthinking:flowbdd:0.1.1-SNAPSHOT")

I am actively looking for real-world use cases! If you're interested in migrating legacy tests or starting a new project with Flow BDD, I’d love to help.

• Maintainer: James Bayliss
• GitHub: jrbayliss
• Repo: https://github.com/techthinking-io/flowbdd
• Website: https://techthinking.io
• With thanks to the Yatspec https://github.com/bodar/yatspec project for the initial inspiration!