How to link test cases back to the requirement (specification) document, and vice-versa

Question

We are slowly generating small automated test cases for some software we develop. We've only got a few dozen or so written so far and we expect that in the end, we will have a few hundred, maybe a few thousands.

My question is what are some of the best practices for linking a test case to the requirement it is testing. Right now all our specifications are Word documents.

A simple way is to put a comment in the test case itself saying that it covers section x.y.z of the specification document, and then a similar comment in the Word document itself saying that this requirement is covered by test cases 1, 2 and 3.

One challenge with that approach is that out requirements documents are also the same documents we give to our clients.

To help understand my situation, I work for a large company and only have control over a subset of the developers (who will also be writing the tests). We don't use Agile or any other formal development process. We already have software in production and are now adding more features and fixing bugs. A solution that requires buy-in from the whole company or all developers or all BA's isn't viable.

Answer 1

I wouldn't link in both directions; this means a lot of effort and may quickly become out of date. Maintaining documentation can also slow down development really bad. From my experience, code tends to be more volatile compared to requirements. Therefore, it's often easier to link test code to requirement documents.

However, test management is a heavily disputed topic. Some use simple Excel sheets, others favor dedicated test management tools. But being successful is influenced by many different factors:

• Project management (classical vs. agile)
• Organizational structure (tall vs. flat)
• Company size (big vs. small)
• Software stack (legacy vs. tested)
• …

I'd start with a simple and lightweight approach. Try it out for a few weeks and talk to developers, testers, and managers afterwards. If everyone is happy, roll it out; otherwise, try something different.

What we do: We're using JIRA Software to formulate requirements (epics/stories/tasks), in which each gets an ID (e.g. ABC-123). As we're using Git Flow as our branching model, each change is developed in a dedicated branch. These branches are named according to the corresponding ID (e.g. feature/ABC-123-fancy-navbar). When a feature is completed with respect to our DoD—which includes a sufficient number of tests—it gets reviewed and automatically merged after its approval. Since the generated merge commit message contains the ID (e.g. "Merged feature/ABC-123-fancy-navbar"), we can easily follow the Git log and see which tests exist for which requirement. Of course, there may be gaps, but we prefer working software over comprehensive documentation. But, as I said, this may not work for others.

Answer 2

how to link automated test cases and requirements

One approach that can help is to use a high level tool such as Cucumber

This effectively means that you have high level tests that work as your requirements and stay in sync with the actual code, e.g.

• Given I am a Logged in User
• When I click the Add Item button
• Then I am taken to the Add Item page

The 'Given, When, Then' format is known as the Gherkin syntax

The ultimate goal being software tests that also perform as human readable documentation. Hopefully these are the sort of documents that you would find suitable to share with your client.

---

Also, during development:

One of the approaches I commonly see used in Agile environments during development is:

• ticket in ticket tracking system (e.g. Jira) with id PROJ-123 and has requirements
• branch gets created that include PROJ-123 in name and has automated tests reflecting those requirements
• branch gets merged in

Of course now the PROJ-123 gets 'lost' as the code is just in master, however at this point that responsibility is handed to the cucumber tests that were created/updated.

Another part I would consider is:

Code Coverage

Consider using a tool such as codecov, code climate, etc. to see how much development code is covered by automated tests.

These are quite different approaches to having fixed requirement documentation and test cases. This is hard but ultimately gives greater flexibility and is why The Agile Manifesto talks about working software over comprehensive documentation. I would say "working software backed by automated tests over comprehensive documentation". The alternative, more fixed linkage tend to leads to regression test suites that keep growing over time and can't be easily refactored or removed and ever growing test suite run times which effectively kill innovation by a slow death.