.................................................................................................................Home / Back to Process Patterns / Back to Test Automation Patterns
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:
  • 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

Recommendations
Automating the tests is also a good time to extract expert knowledge from your manual testers and to document it as automated test cases

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 used this pattern, please add your name and a brief story of how you used this pattern: your context, what you did, and how well it worked - or how it didn't work!
.................................................................................................................Home / Back to Process Patterns / Back to Test Automation Patterns