The SubWiki: Organizing FitNesse Pages into Hierarchies

Why Do We Need Page Hierachies?

FitNesse, you recall, is a wiki, but more than a normal one! A normal wiki is a collection of pages with a flat structure. All the pages are peers. FitNesse, on the other hand, is meant to manage many projects. We'd like each project to have its own wiki hierarchy so that name collisions can be avoided, fixture code can be found easily, etc. We might even need hierarchies within those hierarchies.

For example, project one and project two each have their own TestSuites. Some of the suites might in turn contain smaller suites. These projects probably also use completely different ClassPath definitions. We'd like each project to be able to run acceptance tests using their own ClassPath definitions. So we want a different ClassPath page for each. This is what the FitNesse SubWiki feature makes possible.

How SubWiki Works

A SubWiki is a whole new page hierarchy that lives beneath a single FitNesse page. In fact, such a SubWiki is an entirely separate wiki, with an entirely separate page namespace. Any FitNesse page can be the parent of such a SubWiki. For example the name of this page is <UserGuide.SubWiki. Thus, this page is the SubWiki page whose parent is the <UserGuide page. (Put your mouse on each of these links and look at the bottom of the display to see where they will be directed.) For any such SubWiki, you could have a separate page named SubWiki, and FitNesse would keep them all straight (you might have some trouble, if you did not organize your page links carefully, but that's another story).

Creating a SubWiki

To create a sub wiki, simply create the parent page, and then add pages below it using the ParentPage.SubPage syntax or the shortcut >SubPage markup language syntax.

When a sub-page is displayed, any unqualified links are assumed to be at the current level. If you want to access a global page, you need to precede the link with a dot. For example, from where we are now on this page, the link RecentChanges is really a link to .FitNesse.RecentChanges (which does not exist), whereas the link .RecentChanges is a link to the global page that contains the list of most recently changed pages.

Navigating through Sub Wikis

• Absolute references look like this: .TopPage.MyPage.YourPage where TopPage is at the highest level.
• Relative references look like this: YourPage.MyPage.HisPage where YourPage is a sibling of the page that holds the reference.
• Sub page references look like this: >ChildPage.GrandChildPage where ChildPage is a child of the page that holds the reference.
• Backwards Search References look like this: <AncestorPage.SomePage where AncestorPage is a parent, grandparent, or somewhere up the parent chain. You can use this to search backwards through the page hierarchy until you find the named page.

How Fit Locates ClassPath Definitions in SubWikis

The !r command searches back up the hierarchy of pages looking for pages named ClassPath or !Path definitions. It accumulates all the paths on the way up to the topmost level. Thus you can create global classpaths, project specific classpaths, and even module specific classpaths.

TestSuites: the Perfect Application of the SubWiki

When you organize a suite of test pages, you will naturally want to make each of the individual test pages a child page of the main suite page.

Page Headers and Footers in SubWikis

The PageHeader and PageFooter classes can be used to add specific headers and footers to sub wikis. For example, the headers and footers of this page are comming from <UserGuide.PageHeader and <UserGuide.PageFooter. These headers and footers can be inherited from parent pages. So if there's no PageHeader or PageFooter at the current level, FitNesse will search upwards in the hierarchy until we find one. (See <UserGuide.SpecialPages)

Listing Immediate Child Pages of a Page

The !contents widget will create a list of all the immediate child pages of a parent page.