Using Design by Contract With Jtest

Benefits of Using DbC With Jtest

You do not need to use Design by Contract (DbC) in order to use Jtest. You can, however, increase Jtest's functionality if you use DbC; there are several main advantages to using DbC with Jtest:

Jtest will automatically create black-box test cases that verify the functionality described in your DbC contracts (i.e., Jtest will find inputs that violate the preconditions, postconditions, class invariant contracts, and assert clauses included in the contract).
Jtest will automatically suppress errors for inputs that violate the preconditions of the methods under test.
Jtest will automatically suppress expected uncaught runtime exceptions that are documented using the @exception Javadoc tag.

Jtest and Jcontract

Jtest contains all necessary elements to understand DbC comments and create test cases that check whether the specifications detailed in those comments are indeed implemented. It uses the DbC information to check that the unit in and of itself is implemented correctly.

Jcontract is a new Java development tool that checks DbC contracts at runtime; it is run independently of Jtest, but the two tools are complementary. After you have used Jtest to thoroughly test a class or component at the unit level, instrument it with Jcontract, integrate it into your system/application, then Jcontract will automatically check whether its contracts are violated at runtime. Jcontract is particularly useful for determining whether an application misuses specific classes or components.

Creating DbC Comments

See for a general description of DbC, see About Design by Contract.

See The Design by Contract Specification Language for information on how to add DbC comments to your code.

Jtest's Design by Contract Static Analysis rules help you create well-formed DbC contracts. These rules are not enabled by default. To enable them, perform the following steps:

Open the Global Test Parameters window by clicking Global.
Right-click the Static Analysis> Rules> Built-in Rules> Design by Contract node. A shortcut menu will open.
Choose Enable All from the shortcut menu.

Using DbC Information in Tests

Jtest will use DbC information in its tests as long as the class under test's DbC contracts have been instrumented (by default, they are instrumented as the class is loaded). Just run the test in the normal manner, then Jtest reads specification information built into the class with the DbC language, and automatically develops test cases based on this specification. Jtest designs its black-box test cases as follows:

If the code has postconditions, Jtest creates test cases that verify whether the code satisfies those conditions.
If the code has assertions, Jtest creates test cases that try to make the assertions fail.
If the code has invariant conditions (conditions that apply to all of a class's methods), Jtest creates test cases that try to make the invariant conditions fail.
If the code has preconditions, Jtest tries to find inputs that force all of the paths in the preconditions.
If the method under test calls other methods that have specified preconditions, Jtest determines if the method under test can pass non-permissible values to the other methods.

If Jtest finds inputs that violate preconditions, postconditions, class invariant conditions, and assert clauses, it will report them in the Design by Contract Violations branch of the Errors Found Panel (if you tested a single class) or the Results Panel (if you tested a project).

Jtest also uses the DbC information to automatically suppress exceptions that are not relevant to the project at hand. If you document valid exceptions in the code using the @exception comment tag, Jtest will suppress any occurrence of that particular exception. If you use the @pre comment tag to document the permissible range for valid method inputs, Jtest will suppress errors found for inputs that fall outside of that range.

Example Files

Example DbC files are contained in the <jtest_installation_dir>/examples/dynamic/dbc directory.

Instrumentation Options

If you use DbC comments, Jtest will by default instrument the comments when it loads the class or project under test. You can control whether or not Jtest instruments DbC comments with the Automatically Instrument Design by Contract Comments option in all test parameters' Dynamic Analysis> Test Case Execution branch.