DOCUMENT THE TESTWARE
Pattern summary
Document the automation scripts and the test data.
Category
Process
Context
This pattern is essential for long lasting and maintainable automation. It's not necessary for disposable scripts
Description
Document the automation scripts and the test data, so that they are:
- easily found
- understandable
- reusable
- traceable (e.g. to requirements)
Implementation
Some suggestions:
- Documentation will be easier to write, maintain and read if you SET STANDARDS
- Descriptive names go a long way in documenting what some testware is or does
- use naming conventions consistently to make available testware easy to find
- Use a standard template as the Test Description: document in every script or batch file:
- What does it do
- How do you call it
- What does it return
- other relevant test characteristics (e.g. a smoke test, performance test, feature tested, TEST SELECTOR tags)
- Put the documentation in configuration management together with the testware and the corresponding release of the SUT
- If your current documentation is incomplete, let newbies update it: they learn faster and you get a better documentation
- Automating the tests is also a good time to extract expert knowledge from your manual testers and to document it as automated test cases
Potential Problems
The documentation may not be clear to the intended audience. Get someone to review what is written to make sure it is at the right level of detail and covers what needs to be documented.
Issues addressed by this pattern
DATA CREEP
INADEQUATE DOCUMENTATION
INEFFICIENT EXECUTION
INFLEXIBLE AUTOMATION
KNOW-HOW LEAKAGE
LIMITED EXPERIENCE
OBSCURE TESTS
SCRIPT CREEP
Experiences
Bryan Bakker says: When documenting automated test cases it is a good idea to have the detailed documentation of the test cases in the test scripts directly. Code and documentation are together then, and making sure they are synchronized with every change is a lot easier (maintainability increases). When documentation is still needed (e.g. for reviews, regulatory) documentation can be generated with e.g. Doxygen.
Test designs can still be in documentation of course.
James Tony: Better to use a simple text file to describe what a test does – if that is enough to suit your needs
If you have also used this pattern and would like to contribute your experience to the wiki, please go to Feedback to submit your experience or comment.