What if your code spoke the same language as your business?

Photo by Brett Jordan on Unsplash

The Three Amigos pattern states that people from business, development, and testing perspectives “should collaborate to define what to do, and agree on how they know when it is done correctly”. However, in most IT solutions, there is still a gap between the language spoken by business stakeholders, developers, and testers. This gap leads to miscommunication, ambiguity, and misunderstandings. In practice, there is always a translation step — converting business ideas, use cases, and user stories into production and testing artifacts (i.e., source code).

But what if this translation step didn’t exist?

What if we could use the same language to describe the business, implement the system, and validate it?

I started exploring a testing framework called Guará, which is based on a simple idea:

Break your system into small actions (transactions) and validate their results.

With this approach, you begin writing tests like this:

app.given(UserLoggedIn) \
 .when(Search, product="notebook") \
 .then(ReportChart) \
 .expects(IsEqualTo, 1)

Now the code reads like a story. However, the real breakthrough came when I extended this idea into a business-oriented language. So, instead of using generic words like given, when, and then (the Gherkin style), I asked:

How would a finance professional describe their processes?

The answer led to something like this:

fin_app.account_with(HasBalance) \
 .execute(BuyAsset, symbol="AAPL", amount=2000) \
 .settles(UpdatePortfolio) \
 .reconciles(ExpectedPortfolio, 20)

Now we are speaking the language of the business. This is no longer just test code — it is executable business logic.

One of the most powerful aspects of this approach is that the same building blocks used to describe behavior can also be used to implement it.

For example, a transaction like BuyAsset can be implemented as:

class BuyAsset(AbstractTransaction):
  def do(self, symbol, amount):
    DataBase.balance -= amount

Here, a specific amount is deducted from the customer’s balance and the same transaction can be reused across multiple scenarios — in both tests and production flows — improving consistency, readability, and maintainability. Hence, your tests are no longer just validations. They become living documentation of the system.

How the Framework Works (Simple View)

At its core, the framework is built on three simple concepts:

• Transactions → small units of work (e.g., BuyAsset)
• Application → orchestrates execution (the runner)
• Assertions → validate results

The flow works like this:

• given / when / then → execute transactions
• asserts / expects → validate outcomes

All of this is coordinated by the Application class.

Extending to a Ubiquitous Language (Finance Example)

The real power of this approach is that it can be extended into a domain-specific language. For example, in finance:

• given → account_with, portfolio_with, positioned_with
• when → execute, trade
• then → settles, result_in
• asserts → reconciles, balances

This transforms technical steps into business expressions. In a simple example:

from guara.transaction import Application, AbstractTransaction
from guara import it

# Extends the framework to financial domain
class FinancialApplication(Application):
    def __init__(self, driver=None):
        super().__init__(driver)

    def account_with(self, transaction, **kwargs):
        super().given(transaction, **kwargs)
        return self


    def execute(self, transaction, **kwargs):
        super().when(transaction, **kwargs)
        return self


    def settles(self, transaction, **kwargs):
        super().then(transaction, **kwargs)
        return self


    def reconciles(self, assertion, expected):
        super().asserts(assertion, expected)
        return self


# Transactions that can be used in production and testing code
class BuyAsset(AbstractTransaction):
    def do(self, symbol, amount):
        DataBase.balance -= amount

# Custom assertions derive from base ones, but using the finance terms
class ExpectedPortfolio(it.IsEqualTo):
    def __init__(self):
        super().__init__()

# The domain language used in production code
def main():
    fin_app = FinancialApplication()
    (
        fin_app.account_with(HasBalance)
        .execute(BuyAsset, symbol="AAPL", amount=2000)
        .settles(UpdatePortfolio)
    )

# The domain language used in testing
def test_extend_ubiquitous_language():
    fin_app = FinancialApplication()
    (
        fin_app.account_with(HasBalance)
        .execute(BuyAsset, symbol="AAPL", amount=2000)
        .settles(UpdatePortfolio)
        .reconciles(ExpectedPortfolio, 20)
    )

What started as a testing pattern becomes something much bigger: a way to write software that mirrors real-world thinking. Instead of writing code and then explaining it you write code that is the explanation.

Final Thought

If your code cannot be understood by the business, you are building a system only part of the team can see. But if your code speaks the language of the business… you are not just writing software, you are modeling reality