TestDox for IntelliJ IDEA
This document gives detailed instructions on how to use the plug-in.
The TestDox plug-in provides dynamic documentation for a class based on the names of the test methods defined in the corresponding test class. See agiledox.sourceforge.net for more information on the original TestDox application.
This plug-in introduces convenient ways for adding, renaming, and deleting tests to help produce better TestDox documentation. It also adds the capability to navigate back and forth between a class under test and its corresponding test case.
Simply download TestDox using IDEA's plug-in manager and restart IDEA.
Please note that only IDEA 9.0.x (Maia) is supported.
TestDox can still be downloaded for the following IDEA versions however please note that these are no longer supported!
- IDEA 4.0.x (Aurora)
- IDEA 4.5.x (Pallada)
- IDEA 5.x (Irida)
- IDEA 6.0.x (Demetra)
- IDEA 7.0.x (Selena)
- IDEA 8.0.x (Diana)
The following actions and corresponding keyboard shortcuts can be invoked from within the code editor:
These shortcuts can be remapped in the Keymap configuration panel found under the Settings/IDE Settings dialog.
The corresponding actions are also available as menu items under the TestDox menu situated just after the Refactor menu, both in the editor popup:
and in the editor's main menu bar:
Both Rename Test and Delete Test actions are used as intentions shown when the editor caret is placed on the name of a test method.
Finally, the New Test editor action can be executed from under the Code/Generate popup menu shown using the Alt+Insert keyboard shortcut.
The following actions and corresponding keyboard shortcuts can be invoked from within the TestDox tool window:
The remaining toolbar actions can be described as follows:
- the first toggle button will toggle the TestDox sorting between definition and alphabetical orders
- the second one will toggle the automatic scrolling to the source code of the selected test element
- the last one will refresh the TestDox list of test elements (tested class and test methods)
All TestDox actions will be enabled depending on the current file selection and the position of the editor's caret.
This plug-in features two code inspections which can be configured from the Settings/IDE Settings/Errors dialog under the TestDox Issues category:
- the Test class with no tests inspection reports test classes that do not have any tests and suggests the Add Test action as a quick fix
- the Empty test inspection just reports the presence of empty test methods within a test class. We have decided not to suggest any quick fixes for this.
Test methods can be renamed or deleted from within their code block, including the offset that immediately follows the closing brace of their code block.
When test methods are either added or safely renamed, an input dialog is shown where a test method description can be typed in as a sentence made up of words in lowercase characters separated by space characters. This sentence should describe the intention of the test and will automatically be collapsed back into a method name.
Changes in test classes are instantly reflected in all TestDox views.
The TestDox plug-in provides a configuration panel under the Settings/Project Settings dialog.
Using this panel, you can configure the plug-in so that:
- attempting to navigate from an untested class to its corresponding test class prompts for the creation of the missing test class
- moving a tested class automatically moves the corresponding test class accordingly
- renaming a tested class automatically renames the corresponding test class
- deleting a tested class automatically deletes the corresponding test class
- deleting a package prompts to delete other occurrences of that package
- the name of tested classes is displayed as either a fully qualified or abbreviated class name
Test Class Naming
This section of the configuration panel allows you to specify how your test classes are named. The default is to assume a Test suffix. For example, a class called Foo would have a test class named FooTest. The mapping is defined as a template, where
<classname> is the source class name, and the prefix and suffix are both optional and simply typed into the template where appropriate.
This section allows you to specify where your tests are located. By default, the plug-in will assume that your tests are in a parallel source tree (i.e in the same package as the code they are testing, but in a separate directory on disk). However, if you are unlucky enough to have your tests located using a different strategy, you can use this section to define your custom mappings. As with the test naming, this is achieved using templates. In this case you can have as many templates as required to cover all of your test locations. The templates use two tokens:
which mean the package that the current (non-test) class is in, and a package level "pop", respectively. For example, if the current class is in the package
com.foo.bar.baz, but the test for it is in
com.foo.bar.test, then you would use the following mapping:
You can have as many pop tokens as you need, but they must start and end with the forward slash
You can ativate and de-activate the custom package mapping using the checkbox. De-activating the mapping will not clear any existing entries from the map. To remove entries from the map, click the X button on the right of the entry row. Entries in the table can also be edited by double clicking (or typing into) a row.
The creation of a (test) class can no longer be undone since IntelliJ IDEA 4.5. See IDEA's issue tracker and forums for detailed information on UNDO-related regressions since the Pallada series.
All unresolved issues are listed in JIRA.