Overview

11 Coping with legacy

This chapter explains how BDD can still be valuable when a team is working with legacy software, especially when most of the existing code was created without tests or behavior-focused documentation. The main idea is that teams should not confuse using Gherkin or Cucumber for automation with actually practicing BDD. When behavior is recovered after the fact, the work can help people understand and protect the system, but it is documentation and knowledge recovery rather than true behavior-driven development.

Because legacy systems are usually too large and risky to document all at once, the chapter recommends an incremental, risk-based approach. A practical strategy is to start with areas that are about to change, then document core behaviors that give broad value, and prioritize parts of the system that change most often. This selective approach avoids the maintenance burden of documenting everything and helps teams gradually improve confidence, clarity, and testability without trying to modernize the entire codebase in one step.

The chapter also warns against blindly converting old manual test scripts into automated scenarios. Manual scripts and BDD scenarios often have different goals: scripts are designed to save tester effort, while scenarios are meant to be readable, focused, and fast feedback tools. Instead of treating scripts as direct candidates for automation, teams should use them as clues to valuable behaviors, consult the testers and other experienced team members who wrote or used them, and extract only the information that adds real value. The chapter’s overall message is that legacy systems can be improved through careful, selective BDD adoption, but only when the team focuses on recovering useful knowledge and moving toward test-driven thinking rather than simply automating old habits.

Summary

  • Using Gherkin to capture test scripts is not an indication that the software has been developed in a behavior-driven way
  • Focus retrospective Gherkin documentation efforts on areas of functionality that are about to (or likely to) change
  • Don’t convert manual test scripts directly into Gherkin, because this will not result in good illustrative scenarios
  • Analyze every legacy test script before formulating it into Gherkin to ensure that only valuable documentation is created
  • Make use of any personnel that have knowledge of the legacy product, especially the testers

FAQ

```html
Why is simply using Gherkin for test automation not considered BDD?BDD requires discovery and formulation to happen before implementation, so the scenarios drive development. If Gherkin is only used after code already exists, it is just test automation and not behavior-driven development.
What is the main problem with documenting legacy functionality after it has already been built?It means the team is recovering knowledge after the fact, which is less effective than documenting behavior up front. It also adds unnecessary cost and can negatively affect the system’s architecture.
How should teams choose which legacy functionality to document with Gherkin?Use a risk-based, incremental approach rather than trying to cover the whole codebase. Focus on areas likely to change, core behaviors, or functionality that the team is about to modify.
Why is the 80/20 rule useful when documenting legacy systems?It helps teams get broad value with limited effort by documenting a small set of core behaviors. The idea is to realize most of the benefit from a relatively small amount of work.
Why should teams avoid turning manual test scripts directly into Gherkin scenarios?Manual scripts and BDD scenarios have conflicting goals: scripts optimize tester efficiency, while scenarios optimize readability and fast feedback. Direct conversion usually creates low-value documentation and a large maintenance burden.
Can manual test scripts be used as journey scenarios?Sometimes, but only if they contribute to the big picture. A journey scenario should describe the overall flow, not the detailed checks that belong in focused illustrative scenarios.
What should a team do if a manual test script’s purpose is unclear?They should be cautious about spending too much time analyzing it, because the original intent may be impossible to recover. It is often better to use the script as inspiration for finding useful product areas to explore with example mapping.
Why is it better to ask the tester or original team member instead of only reading the test script?People who worked on the system often have deeper knowledge of the intended behavior than the script itself reveals. Talking to them can give a clearer, more structured understanding of the implemented requirements.
What role can AI play when coping with legacy systems?AI can help reverse engineer behavior by combining source code with documentation, work items, support tickets, logs, and telemetry. It can then suggest areas worth covering with BDD scenarios, though the team’s mindset still needs to move toward test-driven thinking.
What is the best overall strategy for adopting BDD in a legacy codebase?Start small and incrementally, focusing on high-value areas and changing behaviors. Recover the behavior, document it with clear scenarios, and use those scenarios to guide implementation and future changes.
```

pro $24.99 per month

  • access to all Manning books, MEAPs, liveVideos, liveProjects, and audiobooks!
  • choose one free eBook per month to keep
  • exclusive 50% discount on all purchases
  • renews monthly, pause or cancel renewal anytime

lite $19.99 per month

  • access to all Manning books, including MEAPs!

team

5, 10 or 20 seats+ for your team - learn more


Close
choose your plan

team

monthly
annual
$49.99
$499.99
only $41.67 per month
  • five seats for your team
  • access to all Manning books, MEAPs, liveVideos, liveProjects, and audiobooks!
  • choose another free product every time you renew
  • choose twelve free products per year
  • exclusive 50% discount on all purchases
  • renews monthly, pause or cancel renewal anytime
  • renews annually, pause or cancel renewal anytime
  • Effective Behavior-Driven Development Effective Behavior-Driven Development ebook for free
Close
choose your plan

team

monthly
annual
$49.99
$499.99
only $41.67 per month
  • five seats for your team
  • access to all Manning books, MEAPs, liveVideos, liveProjects, and audiobooks!
  • choose another free product every time you renew
  • choose twelve free products per year
  • exclusive 50% discount on all purchases
  • renews monthly, pause or cancel renewal anytime
  • renews annually, pause or cancel renewal anytime
  • Effective Behavior-Driven Development Effective Behavior-Driven Development ebook for free