Chapter 11: Coping with legacy
Introduces why adopting BDD while working with existing code matters, using the WIMP team as an example.
After this chapter you will be able to
- Legacy code and BDD adoption. Explain why code already written when a team adopts BDD can be considered legacy code, and why adopting BDD practices in that situation matters.
- BDD versus retrospective scenarios. Distinguish using discovery and Gherkin scenarios to document or test implemented functionality from using them to drive development. Explain that BDD requires discovery and formulation before writing the implementation code.
- Costs of documenting behavior late. Explain why recovering requirements after implementation is less effective, including its cost and the architectural and automation difficulties the section associates with code not developed in response to failing scenarios and tests.
- Incremental legacy documentation. Explain why teams should generally avoid applying discovery and formulation to an entire legacy codebase and instead adopt a risk-based, incremental strategy suited to their context.
- BDD in areas being changed. Explain why the team applies discovery and formulation to a legacy codebase area it is about to modify, and describe how it proceeds once existing behavior is documented.
- Core behavior selection. Explain how teams seeking broad documentation coverage can apply the 80/20 rule by having domain experts identify a few core behaviors across the application to document.
- Change-based documentation priorities. Explain why frequently changing areas of a legacy system are more valuable to document than areas that rarely change, and how source control can help identify them.
- Scenario design goals. Distinguish why illustrative scenarios focus on one behavior while manual test scripts often cover many behaviors in detail.
- Direct script conversion costs. Explain why simply formulating manual test scripts for automation is usually a poor approach.
- Journey and behavior focus. Distinguish a journey scenario’s focus on the overall flow from an illustrative scenario’s focus on a particular behavior, and explain why a detailed manual test script is not automatically a useful journey scenario.
- Selective reuse of test scripts. Describe how a team can extract useful specifications from manual test scripts: assess each script, formulate relevant illustrative scenarios, and create a journey scenario only when it adds to the big picture.
- Using old manual test scripts. Explain when a manual test script can provide the basis for an automated illustrative scenario, why analyzing an unclear script may waste time, and how teams can use old scripts and example mapping instead.
- People Behind Legacy Scripts. Explain why talking to people who worked on a legacy implementation can give a more structured view of its requirements than reading test scripts alone, especially when testers are available.
What it builds on
- How BDD works (chapter 1) · The earlier account of how BDD works.
- Using example maps to provide focus (chapter 7) · The earlier use of example maps to focus scenarios.
- Discovery (chapter 1) · The discovery phase of BDD.
- Formulation (chapter 1) · The formulation phase of BDD.
- Automation (chapter 1) · The automation phase of BDD.
- Keep your scenarios BRIEF (chapter 7) · The BRIEF principles for illustrative scenarios
- Journey scenarios (chapter 10) · The idea of journey scenarios.
- Example Mapping in a nutshell (chapter 2) · Example mapping as a way to clarify uncertain requirements
Section by section
Introduction
Introduces why adopting BDD while working with existing code matters, using the WIMP team as an example.
- Legacy code and BDD adoption: Explain why code already written when a team adopts BDD can be considered legacy code, and why adopting BDD practices in that situation matters.
Why it matters: A team need not be starting a new product for BDD adoption to be worthwhile.
Key terms: legacy code, BDD practices
11.1 BDD on legacy projects
The section distinguishes recovering and testing existing behavior from BDD that drives development, explains the costs of documenting behavior late, and describes a limited role for AI in modernizing legacy systems.
- BDD versus retrospective scenarios: Distinguish using discovery and Gherkin scenarios to document or test implemented functionality from using them to drive development. Explain that BDD requires discovery and formulation before writing the implementation code.
Why it matters: The timing and purpose of scenarios matter more than the tool or format used. - Value of recovered behavior: Describe how example mapping and illustrative scenarios can recover knowledge about legacy code, and what that knowledge is useful for now and later.
Why it matters: Recovering behavior is worthwhile even when it cannot change how the original code was developed. - Costs of documenting behavior late: Explain why recovering requirements after implementation is less effective, including its cost and the architectural and automation difficulties the section associates with code not developed in response to failing scenarios and tests.
Why it matters: Writing scenarios after the fact cannot recover the design benefits of developing in response to them. - AI assisted legacy discovery: Describe how additional information sources can help AI reconstruct system behavior and suggest scenarios, while stating the section’s caution about what constitutes success.
Why it matters: AI may help uncover legacy behavior, but it does not substitute for changing how the team develops software.
Key terms: Behavior Driven Development, discovery, formulation, Gherkin scenarios, Cucumber, example mapping, illustrative scenarios, current behavior, failing scenarios and tests, tightly coupled architectures
11.2 Incremental documentation
This section recommends a risk-based, incremental approach to documenting a legacy codebase rather than applying discovery and formulation to all of it at once.
- Incremental legacy documentation: Explain why teams should generally avoid applying discovery and formulation to an entire legacy codebase and instead adopt a risk-based, incremental strategy suited to their context.
Why it matters: You can improve legacy documentation without taking on the entire codebase at once.
Key terms: discovery, formulation, legacy codebase, risk-based, incremental strategy
11.2.1 New behaviors
This section explains how a team can begin using BDD in a legacy codebase by documenting existing behavior in an area it is about to change, then using BDD to guide implementation.
- BDD in areas being changed: Explain why the team applies discovery and formulation to a legacy codebase area it is about to modify, and describe how it proceeds once existing behavior is documented.
Why it matters: The team can build confidence where it needs to make a change without first documenting the entire codebase.
Key terms: discovery, formulation, example map, business readable documentation, automation
11.2.2 The 80/20 rule
The section recommends documenting a small set of core behaviors for broad coverage of a legacy system while limiting journey scenarios to avoid maintenance costs.
- Core behavior selection: Explain how teams seeking broad documentation coverage can apply the 80/20 rule by having domain experts identify a few core behaviors across the application to document.
Why it matters: It offers a manageable way to document the most valuable parts of an existing system. - Focused behaviors over journeys: Justify documenting focused behaviors rather than many journey scenarios when applying this approach.
Why it matters: Keeping journey scenarios limited helps the documentation remain maintainable.
Key terms: 80/20 rule, Pareto Principle, domain experts, core behaviors, focused behaviors, journey scenarios, maintenance burden
11.2.3 Probability of change
Prioritize documenting frequently changed parts of a legacy system, and recognize that starting BDD later can still help stabilize releases.
- Change-based documentation priorities: Explain why frequently changing areas of a legacy system are more valuable to document than areas that rarely change, and how source control can help identify them.
Why it matters: This gives the team a practical way to focus limited documentation effort. - Value of starting BDD later: Explain what the legacy-project story illustrates about adopting BDD after a system is already in use.
Why it matters: A team need not abandon BDD simply because its project is already a legacy system.
Key terms: source control system, documenting, change frequently, BDD, legacy system, well selected scenarios
11.3 Making use of manual test scripts
The section introduces the question of what to do with existing manual test scripts on a team adopting BDD.
11.3.1 Conflicting goals
The section contrasts the goals of illustrative scenarios and manual test scripts, then explains why directly converting manual scripts into automated scenarios is usually a poor choice.
- Scenario design goals: Distinguish why illustrative scenarios focus on one behavior while manual test scripts often cover many behaviors in detail.
Why it matters: The two kinds of scenarios are shaped by different costs, so a useful manual script may not make a useful illustrative scenario. - Direct script conversion costs: Explain why simply formulating manual test scripts for automation is usually a poor approach.
Why it matters: Avoiding direct conversion helps preserve readable documentation without inheriting an unnecessarily costly script to maintain.
Key terms: illustrative scenarios, BRIEF, manual test scenarios, manual test scripts, formulate, maintenance burden
11.3.2 Not all journeys are informative
Explains why manual test scripts should be analyzed rather than automatically turned into journey scenarios.
- Journey and behavior focus: Distinguish a journey scenario’s focus on the overall flow from an illustrative scenario’s focus on a particular behavior, and explain why a detailed manual test script is not automatically a useful journey scenario.
Why it matters: The distinction keeps journey scenarios focused on the overall flow rather than every detail encountered along the way. - Selective reuse of test scripts: Describe how a team can extract useful specifications from manual test scripts: assess each script, formulate relevant illustrative scenarios, and create a journey scenario only when it adds to the big picture.
Why it matters: Assessing scripts individually preserves useful information without creating journey scenarios that add little value.
Key terms: journey scenario, illustrative scenarios, manual test scripts, big picture
11.3.3 Shortcuts don’t always save time
This subsection explains why old manual test scripts are more useful as prompts for discovering behavior than as documents to analyze exhaustively.
- Using old manual test scripts: Explain when a manual test script can provide the basis for an automated illustrative scenario, why analyzing an unclear script may waste time, and how teams can use old scripts and example mapping instead.
Why it matters: This approach directs effort toward understanding useful behavior rather than guessing at an old script’s intent.
Key terms: manual test scripts, automated illustrative scenario, example mapping, knowledge recovery
11.3.4 Ask the tester, not the test script
Use the knowledge behind legacy test scripts—especially testers’ expertise—to recover implemented requirements, while treating AI-generated scenarios as suggestions to review.
- People Behind Legacy Scripts: Explain why talking to people who worked on a legacy implementation can give a more structured view of its requirements than reading test scripts alone, especially when testers are available.
Why it matters: You can preserve what the scripts capture without overlooking the expertise of the people who used them. - AI Assisted Scenario Suggestions: Describe how an AI agent might use questions about a manual script to suggest illustrative, rule-connected scenarios, and why the team must review those suggestions.
Why it matters: Questions about business intent can make AI suggestions more useful, but they do not replace human judgment.
Key terms: test scripts, example mapping, domain knowledge, testers, manual test scripts, business intent, AI agents, illustrative scenarios, rules
11.4 Summary
Concepts explained in this chapter
- manual test scriptA written sequence of instructions for a person to execute a software test manually.
- behavior-driven developmentAn activity that applies behavior-driven development principles during software development.
- illustrative scenarioA concrete narrative describing a representative situation, context, and expected behavior for a business requirement.
- documentationDocumentation is recorded information describing a system and its behavior for reference and maintenance.
- formulationThe behavior-driven development practice of expressing understood behavior as precise scenarios.
- journey scenarioA scenario that describes a complete user journey and the end-to-end flow through which a system delivers useful outcomes.
- GherkinA domain-specific language for writing human-readable behavior specifications using constructs such as Given, When, and Then.
- automationAutomation is the behavior-driven development practice of making specified scenarios executable so that software behavior can be checked automatically.
- example mapAn example map is a visual arrangement of examples and their associated rules for examining how a system should behave in different situations.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.
