An understandable potential concern with declarative testing using annotations is the thought of adding tests within your production code. A key design axiom of Sureassert Exemplars is to avoid any dependencies on test code from production code. The Sureassert engine performs test execution within a testing context using data defined in your Exemplars, but the Exemplars themselves do not contain test code.
Declarative tests – Exemplars – can be considered as meta-data, or documentation, that is complimentary to your method contracts. It is common (and most would consider best-practice) to specify method contracts within the Javadoc of your methods. For example specifying what the method does, detailing the arguments it expects, return values, pre-conditions, etc. This effectively forms the method specification.
In addition you may document example usage scenarios within your method javadocs that adhere to the specification. Exemplars effectively formalize this type of documentation. it’s quite valid to think of Exemplars as describing how your code should be used (i.e. how your methods should be invoked), rather than describing executable tests. In reality, as a by-product of formalizing the former, the latter is made possible.
It’s also worth noting that often a method’s documented contract and interface is decoupled from its implementation through the use of interfaces or abstract classes. Just like Eclipse inherits documentation from a method’s interface or abstract class, so Sureassert UC inherits and executes Exemplars defined for a method in its interface or abstract class. This is a good way of separating both the interface and specification of a method (including Exemplars,) from its implementation.