[ANN] TestDox IDEA Plugin v1.0 released


The following README is re-formatted from http://www.intellij.org/twiki/bin/view/Main/TestDoxPlugin for your convenience.

Purpose

The Testdox IDEA Plugin provides dynamic documentation for a class based on the names of the test methods defined in the corresponding test case. See http://agiledox.sourceforge.net for more information on the original TestDox application.

This plugin introduces convenient ways for adding, renaming, and deleting tests to help produce better TestDox documentation. It also adds the capability to jump back and forth between a class under test and its corresponding test case.


Installation

Simply download Testdox IDEA Plugin v1.0 using IDEA's plugin manager and restart IntelliJ IDEA.

Please note that only IDEA 4.0.x (Aurora) and IDEA 4.5.x (Pallada) are supported.


Usage

The following actions and corresponding keyboard shortcuts can be invoked from within the code editor:

AltShiftD - Shows/Hides the TestDox tool window
AltShiftQ - Shows/Hides QuickDox, a draggable tooltip view of the TestDox tool window
AltShiftT - Navigates back and forth between a tested class and its corresponding test case

AltShiftN - Adds a new test method to a test case
AltShiftF6 - Renames the current test method
AltShiftDelete - Deletes the current test method

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 in both editor popup and 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 AltInsert+ keyboard shortcut.


The following actions and corresponding keyboard shortcuts can be invoked from within the TestDox tool window:

Up/Down - Selects a test element from the TestDox list
Enter - Navigates to the source code for the selected test element (also activated on double-click)
F6 - Opens a dialog for safely renaming the selected element (tested class or test method)
Delete - Prompts for safely deleting the currently selected test element (tested class or test method)
Escape - Closes the window when floating / Switches focus to the code editor when docked

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.


Inspections

This plugin features two code inspections which can be configured from the Setting/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.


Behaviour

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.


Configuration

The Testdox IDEA Plugin provides a configuration panel under the Settings/Project Settings dialog.

Behaviour
Using this panel, you can configure the plugin 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.

Test Packaging
This section allows you to specify where your tests are located. By default, the plugin 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:

<package> and /..

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:

<package>/../test

You can have as many pop tokens as you need, but they must start and end with the forward slash '/' character.

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.


Known Issues

The creation of a (test) class cannot be undone under IntelliJ IDEA versions 4.5.0 and 4.5.1. See IDEA's issue tracker and forums for detailed information on UNDO-related regressions in the Pallada series.


Feeback

Please post your comments either here or on the IntelliJ TWiki: http://www.intellij.org/twiki/bin/view/Main/TestDoxPluginDev

Your feedback is much appreciated!

Please sign in to leave a comment.