Zum Inhalt springen
← Alle Artikel

Dieser Inhalt ist nur auf Englisch verfügbar.

Can SquashTM serve as the design memory for an application?

SquashTM "Add a requirement" form for requirement EXG-LIV-001

Teams change, and the reasons behind business rules often leave with them. Through a single example, this article shows how requirements, test cases and their versions in SquashTM can record what an application does and why — work done by testers that serves everyone who maintains the application, not only QA.

By Fanny Velsin

Two or five years from now, if your entire team has changed, will you still be able to understand not only how the application is supposed to function, but also why it was designed that way?

“Mystic Meg used to handle that area, she was the one who knew the business rules.”

This might sound familiar. Mystic Meg left, and then others followed. The developers, the Product Owner, and the testers who were present when the features were first designed have all moved on, and some of their knowledge went with them.

Imagine a new team discovers a restriction: a customer cannot change the delivery address for an order once it has been confirmed. No one can explain why, after all, allowing a correction before shipment would seem to be a helpful service to the customer.

A Business Analyst formalizes this change, the team implements it, and tests confirm that the new address is correctly saved and displayed on the order.

And then… disaster strikes. The package is shipped to the old address.

The warehouse had received the address at the moment the order was confirmed; the interface between the two systems did not transmit subsequent changes. The restriction had been put in place precisely to ensure that the address shown to the customer would always match the one used for shipping.

At the time, the team had decided to keep this restriction until the interface could be updated, but the reasoning behind this choice was never documented.

So, how can you preserve both the business rules and the rationale behind them? Let’s look at a three-step approach to help minimize this loss of knowledge, without creating an overwhelming number of tickets and documents.

1. Keep what the application is supposed to do

The first step is to make the expected behavior of the application explicit.

In our hypothetical example, the initial rule could be stated as follows: “A customer may change the delivery address for an order as long as that order has not yet been confirmed. Once confirmed, such a change is no longer permitted.”

It is also necessary to define the scope. Are we referring to the address saved in the customer’s account, or the one associated with a specific order? In this case, the restriction applies to the address of a confirmed order. Modifying one’s address book for future purchases is a different behavior.

Business requirements, business rules, and user journeys help formalize these expectations. Test cases then serve to illustrate and verify them in concrete scenarios, such as changing an address before confirmation, confirming that such a change is impossible after confirmation, or ensuring that an update to the address book does not affect an order that has already been confirmed.

For example, here is the requirement:

SquashTM "Add a requirement" form for EXG-LIV-001, "Changing a delivery address for an order", with a Scope section and two business rules: BR01, the customer can change the delivery address before the order is confirmed; BR02, they can no longer change it once the order is confirmed.
Requirement EXG-LIV-001 at creation: scope and business rules BR01 and BR02. View full size

And the 2 test cases:

Test case CT-LIV-001, "Change the delivery address before order confirmation", in SquashTM: information tab, linked to requirement EXG-LIV-001.
Test case CT-LIV-001, linked to requirement EXG-LIV-001. View full size
Prerequisites and test steps of CT-LIV-001: open the unconfirmed order, replace address A with address B and save, then reopen the order; address B is still displayed.
CT-LIV-001 test steps: changing the address before confirmation. View full size
Test case CT-LIV-002, "Verify that the delivery address cannot be changed after order confirmation", in SquashTM: information tab, linked to requirement EXG-LIV-001.
Test case CT-LIV-002, linked to the same requirement. View full size
Prerequisites and test steps of CT-LIV-002: open the confirmed order, check the available actions (none allows changing the delivery address), then reopen the order; address A remains unchanged.
CT-LIV-002 test steps: no address change once the order is confirmed. View full size

In SquashTM, requirements and their associated test cases can serve as a foundation for this organization. A requirement describes an expectation, while tests specify how to verify it.

The goal is to enable someone encountering the functionality for the first time to understand its behavior, conditions, and limitations. Yet, one question remains: why prevent a modification that appears useful to the client?

2. Document the reasons why the application was designed this way

In our example, the blockage stems from a limitation in the interface with the warehouse. The delivery address is transmitted when an order is confirmed, but any subsequent changes are not communicated to the warehouse system.

Consequently, the team decided to prohibit such changes to prevent a discrepancy between the address displayed in the application and the one used for shipping.

This explanation changes how the rule is interpreted. The restriction is a response to a specific technical constraint. If the interface were to evolve, it would be worth re-evaluating this decision.

Without this context, a new team might keep the restriction in place, assuming it is a permanent business requirement, or, conversely, they might remove it without realizing the risk it was intended to prevent.

Expected behavior and its underlying rationale are two distinct pieces of information. A test can verify that a change is prohibited, but it cannot explain why that prohibition exists. Even a series of successful tests is not enough, on its own, to reveal the original reasoning behind the decision.

In this case, a few key details would clarify the situation: the interface limitation, the risk of shipping to an incorrect address, a reference to the original decision, and the conditions under which the restriction could be reconsidered.

SquashTM provides descriptions and custom fields for requirements. A team can leverage these features to organize the information they wish to retain. Custom fields require configuration, and the entire setup necessitates a shared documentation convention. The tool does not automatically infer the rationale behind a decision from the content of the tests.

The justification can be documented alongside the requirement or accompanied by a reference to an authoritative source document. The key is to ensure it remains easily retrievable, avoiding the need to repeat the same explanation within every individual scenario.

However, this approach has a limitation: documenting a rule and its justification does not capture the application’s entire architecture. The detailed mechanics of an interface with a data warehouse, for instance, might be covered elsewhere. The repository should make it possible to identify such external sources and understand their connection to the behavior being tested.

Finally, if a justification is unknown, it should be presented as such. If no one knows why a particular constraint exists, it is better to flag it as an open question rather than presenting a plausible explanation as a certainty.

Version 1 of requirement EXG-LIV-001. Besides the scope and business rules, its description has three sections: Identified constraint (address changes after confirmation are not sent to the warehouse), Design decision (changes are blocked once the order is confirmed) and Condition for review (when the interface can send changes and receive the warehouse's confirmation). Two test cases, CT-LIV-001 and CT-LIV-002, verify it.
Version 1 of the requirement, with the identified constraint, the design decision and the condition for review. View full size

Below, within the requirement description, I supplement the business rules with 3 sections: the identified constraint, the chosen decision, and the condition for re-evaluation.

3. Transmit this understanding over time

Let’s revisit the situation two years later. The interface with the warehouse can now transmit address changes and receive confirmation that they have been processed. The team is considering allowing modifications after an order has been validated, up until the point when order preparation begins.

They look back at the original rule and the reasoning behind it. This allows them to verify whether the previous constraint has truly been lifted and to define the new conditions for making changes.

The issue now extends beyond simply recording an address within the application. At what point can the warehouse still accept a change? What should the application display while awaiting confirmation? What happens if the transmission fails?

Tests must take these decisions into account. Simply verifying that the new address appears on the screen is not enough to demonstrate that it will be used for shipping; checks must also be included to ensure the address is correctly transmitted to and processed by the warehouse.

SquashTM offers versioning for requirements. Multiple versions can coexist, each with its own content, lifecycle, and associations with test cases. When creating a new version, the options for handling existing data must be considered: carrying over test cases links them to the new version while detaching them from the previous one. Consequently, versioning does not provide a complete, automatic snapshot of the entire repository.

Version 2 of requirement EXG-LIV-001: five business rules allowing an address change after confirmation until warehouse preparation begins, subject to the warehouse's acknowledgement, followed by the sections Updated design rationale and Reason for this revision. No test case is linked to this version yet.
Version 2 of the requirement: updated business rules and the reason for the revision. View full size

To illustrate this evolution, I retain the original rule and its justification within version 1 of the requirement. I then create a version 2, which outlines the new conditions for modifying the address and explains why the previous restriction can now be relaxed.

Consequently, the existing tests remain linked to version 1. To verify version 2, it will be necessary to prepare test cases that correspond to the new behaviors and associate them with that version. The following table presents the scenarios under consideration.

ReferenceTest case name
CT-LIV-001Change the delivery address before order confirmation
CT-LIV-002Change the delivery address after order confirmation and before warehouse preparation
CT-LIV-003Verify that the delivery address cannot be changed once warehouse preparation has begun
CT-LIV-004Confirm the address change after warehouse acknowledgement
CT-LIV-005Handle an address change rejected by the warehouse
CT-LIV-006Handle a missing warehouse acknowledgement

The test that verified the prohibition on modifying the address after confirmation remains relevant for describing the previous behavior. For the new behavior, it is necessary, among other things, to verify that modification is permitted before the preparation phase begins and prohibited thereafter.

The list of versions makes it possible to track the two states of the requirement and understand the reasons for their evolution. This structure preserves the successive descriptions and their associations with the tests; it does not, however, constitute an automatic snapshot of the entire repository.

This updating process must be integrated into day-to-day work. Who updates the rule? Who confirms that a constraint is no longer in effect? Who verifies the associated scenarios? Maintaining this knowledge requires input from those who define requirements, make technical decisions, and design tests.

To evaluate this approach, you could task someone unfamiliar with a given feature to work with it. Can they determine the expected behavior, understand the reason for an initial restriction, and identify what led to its evolution? Any questions that remain unanswered point to concrete areas for improvement.

Can SquashTM serve as the design memory for an application? It can certainly contribute to this, provided the team documents expectations, their underlying justifications, and their links to verification processes, and keeps this information up to date.

The initial question thus becomes a guiding criterion for documentation: two years from now, will another team be able to understand this rule, grasp the reasons behind it, and make an informed decision on whether to keep it or evolve it?