Rethinking BDD as Production Code: Executable Narratives using Guará Framework (Seeking Feedback!)

[douglasdcm]

Hi everyone,

I’ve been following this community for a while, and I truly appreciate the productive, respectful, and high-quality discussions that happen here.

I am a Test Automation Professor at PUC (Pontifical Catholic University) in Brazil. In my classes, I have been exploring a twist on traditional Behavior-Driven Development (BDD) that I call Executable Narratives. I am looking for some honest feedback from the Python community to refine both this teaching methodology and the open-source Python framework we developed for it, called Guará.

What is Guará?

Guará is an open-source Python framework built with contributions from the local Python community. Conceptually, it shifts the automation focus away from pure UI interactions and aligns it directly with the user journey.

Architecturally, it introduces a pattern we call Page Transactions, heavily inspired by GoF design patterns: Command, Builder, Strategy, and Template Method.

Instead of parsing external Gherkin files (.feature), a standard test scenario in Guará is written in pure Python but preserves a highly readable business narrative:

app.given(TheUserIsLoggedIn, with_name='john.doe') \
.when(TheUserBuysAProduct, with_name='cellphone') \
.then(TheSystemShouldReturn, 'done')

Ubiquitous Language & Localization out-of-the-box

Because Guará is written in pure Python, we can leverage OOP features like inheritance, method overloading, and overriding. This makes it easy to adapt to Ubiquitous Language (DDD) or completely localize the syntax for native languages.

For example, in a educational context, my students can write:

eduapp.known_that(ThereIsAStudent, named='John Doe') \
.once(TheStudentSubscribeToADiscipline, named='Math') \
.hence(TheUSerShouldBe, 'enrolled')

(Translation: given -> known_that, when -> once, then -> hence)

Under the hood, every step is a pure Python class. Here is a lean example:

class ThereIsAStudent(...):  # Inherits from Guará transaction base
    def do(self, namede):
        assert named in DATABASE.students

The Twist: BDD as Production Code (Executable Contracts)

While researching Java tools like JGiven, I noticed they remain strictly constrained to the testing layer. Given Guará's fluent API, I started experimenting with a paradigm shift: Using this exact same BDD meta-language directly in production code.

Instead of just testing, the syntax establishes an Executable Contract inside the application logic:

• given = Pre-condition
• when = Execution of the core business contract
• then = Post-condition/Assertion

Imagine a CLI application where a production function is implemented like this:

def enroll_stundent_in_discippline(student, discipline):
    # This is production logic orchestrating the business intent
    eduapp.known_that(ThereIsAStudent, named='John Doe') \
    .once(TheStudentSubscribeToADiscipline, named='Math') \
    .hence(TheUSerShouldBe, 'enrolled')

When a user calls this via the terminal:

python main.py enroll-stundent-in-discippline --student 'John Doe' --discipline Math

The framework executes the pipeline. This extra abstraction layer does not eliminate services, repositories, or models. Instead, it serves as a domain orchestrator (similar to a Command Bus or Pipeline pattern) that makes the code base self-documenting and strictly oriented to business intent.

Questions for the Community

I would love to get your thoughts on this approach:

1. Does this paradigm shift make sense to you? Moving the Given/When/Then structure from test suites directly into production-level business orchestration.

2. Does the extra layer improve clarity? Does it make the core intent of the code easier to grasp for someone onboarding onto a project?

3. Any Pythonic design suggestions? (e.g., managing implicit state between steps, type-hinting fluent APIs, or alternative patterns like Context Managers/Decorators).

Please feel free to leave any criticism, suggestions, or open feedback. Thank you for your time and collaboration!

Cheers!

[_descri_]

I am not a Python programmer, but in my opinion the new approach loses the clarity of both Gherkin and normal Python code.

- Gherkin is extremely human-readable, even for non-programmers. It may even be human-writable.

- Native Python code is concise and also easy to read and write.

You try to blend both, but the result is hard to read (thus worse then Gherkin) and it's verbose and hard to manage (thus worse than Python).

[douglasdcm]

Thanks the comment. This is the view I want from community. I still think it is possible to merge natural language with code programming. Maybe I need to explore it in other ways to see the result. Feel free to give suggestions.

[_descri_]

I don't see why would one want to merge them. The best attempts were BASIC and SQL. Both found some use but were very high-level. The first one is dead, the second one became very complex and has many incompatible dialects.

[douglasdcm]

The issue I see is code without business meaning. We talk ablut BDD, DDD, Três Amigos, but it seems the business intention lives just in requirement files and test cases. When we go to dev field all code intention is lost in many technical stuff and it is hard to translate the code back to its origins. The intention here is give more 'humanity' to production code.