Video Transcript

Hello, this is Amir Shehata with another quick tip on the LUTF.

Today I'd like to express my thoughts on the software process.

Problems with the Traditional Software Development Model

We all learnt the waterfall model at school. I don't know about you, but in practice it never is that clean.

...

As we write the HLD, we find we need to role back and adjust the requirements. The Detailed design is often passed over in favour of going directly to implementation, which I can't really disagree with.

A compromise is to develop the HLD in enough details that we can jump directly into implementation.

The Test Plan is written at the very end.

Bug fixes happen during implementation and testing and often result in design changes and event requirement changes. We endup with a bit of a messy development processIn my experience what often happens is that the Test plan is left to the very end. When we get to it we sometimes discover a missing requirement or a missing element of the design.

Under deadlines what inevitably ends up happening is the documentation goes stale.

...

I contend that there exists no zero effort solution. Any solution will need adjusting the development workflow, which will appear like extra effort.

The trick is to reduce the cost of the solution and maximize the benefit.

Before I get to my proposal, a disclaimer. I'm a strong proponent of formalized documentation, but I'm flexible on the form this formalized documentation looks like.

One of the big problems with maintaining a test plan is developers need to create a test plan document which is separate from the test scripts.

What, inevitably, ends up happening is that as the product evolves, bugs get fixed, etc, more test cases are added, but the test plan is not updated.

Even more problematic is that the design diverges and the HLD and/or requirements are not updated.

Proposed Solution

My proposed solution is to bring the test plan development to the centre of the Software Development Process.

A well formed requirement must be testable. Therefore we can represent each requirement as a test case.

Each requirement must be designed. The details of the design can also be added to the test case.

We write the HLD (as we would normally) and add extra test cases as needed. The test cases would test existing requirements or add new discovered requirements we didn't think of before.

We move to implementation (either after the HLD is completed or in parallel) and add extra test cases as needed. Again these test cases can test existing requirement or add new ones.

Once the feature is complete we should have a set of test scripts which represent both the requirements, test plan and parts of the design.

The LUTF Involvement

Let's now imagine that all these test scripts, which include:

• the requirements
• the details on how the Requirements will be designed and
• the test case description

are LUTF test scripts.

We can use the LUTF to automatically extract all this information from the test scripts and generate our documentation.

As you can see we no longer need to keep 3 different documents: A requirements document, an HLD document and a Test plan document.

With this work flow the requirements, design and the test plan and the test plan implementation is collapsed into one form: the LUTF test scripts. From the test scripts we can generate our documents.

I believe this reduces the overhead and increases our chances of keeping documentation consistent with the implementation.

The LUTF Documentation Block

...

Each test script should include a documentation block formatted as follows:. Not all elements shown here are needed. But the more complete it is the more complete the generated document will be

Code Block
""" @PRIMARY: sample_01 Primary Requirement ID @PRIMARY_DESC: Primary Requirement ID description @SECONDARY: sample_01 @DESCRIPTION: Simple Hello Lustre testSecondary Requirement ID if it exists @SECONDARY_DESC: Secondary Requirement ID description if it exists @DESIGN: Design notes and description @TESTCASE: Test case descrtiption """

It's enclosed in """ .

• @PRIMARY: is the primary requirement this script fulfills
• @SECONDARY: is the secondary requirement, if any, this script fulfills
• @DESCRIPTION: Is a detailed description of the test case

By specifying these, the LUTF can generate automatic documentation for the test scripts. We no longer need to maintain a separate test plan. Our test scripts become our test plan.The LUTF can automatically generate the bulk of the requirements, HLD and test plan documentation from the test scripts.

This method provides the glue between the code and the documentation. As bugs are fixed or the feature updated, the developer should create a new test case cases to cover the changes made .Each test case should have a documentation blockand regenerate the documentation.

The LUTF then provides a method to extract the documentation block and create a table which can then be imported to the wiki. In this way it becomes much easier for the developer to maintain appropriate documentation without much overhead.One way of working would be to create a skeleton of the scripts which just include the above comment block. Then run the can generate documentation with the create_docs() command on the suite.

Code Block
suites['samples'].create_docs("samples.csv")

This will generate a csv file with all the documentation.two csv files one would be the requirement document with the design and the other is the test plan.

Requirement Document

Requirement ID	Requirement Description

HLD

Requirement ID	Design Notes

Test Plan

Primary Requirement ID	Secondary Requirement ID	Test Case  Description

NOTE: each secondary requirement in a test case should be a primary requirement in another test case. The idea here is that some test cases might touch on more than one requirement.

The csv files This can then be imported directly into the Confluence wiki or embedded in a document.

Once the test plan is reviewed, updated and approved, the script logic can be written in a separate phase.

Caveat

Of course life is always more complicated that it appears on paper.

Diagrams and other mediums might be needed to explain the requirements and the design, which can not be included in the text only test script.

However, my argument is that the above process can alleviate much of the maintenance of the documents required.

Lets take the Requirements document as an example.

The first section can have the overview and diagrammatic explanations required. The second section is the table detailing all the requirements.

Let's look at how all this would look like in the LUTF.

Demonstration

Let's run through this process to show how easy it is.