• arbiter
• overview
• roadmap
• resources
• download

What is Arbiter?

Arbiter is a requirements gathering and verification tool for web projects. It's aim is to sharpen the communication between stakeholders and developers.

Arbiter itself runs as a simple document repository on a web server. When requirements documents are added or updated, they are scraped of test cases and these tests are run. Tests are just examples of how someone would use a web browser to get information from the site.

For example...

Arbiter will run this sequence of instructions and write back the results like so... The new document can be immediately downloaded back. In addition a summary of the results is displayed.

The results of these tests are immediately displayed on the web page and a modified document is available for download with the test results inserted in the text. As the project progresses, more and more of these tests will pass. This allows the stakeholders to monitor progress.

As the requirements documents must contain very explicit examples of the actions their web site is supposed to perform, the web developers have a very clear idea of when their goals have been achieved. If the task is not clear than more explanation can be added to the requirements documents. The web developers can also ask for more examples or clarification of terms.

How does it work?

It takes normal requirements documents in rich text format, as may be produced from Microsoft Word(tm) for example, and extracts key pieces of information from them. Arbiter is after two types of information here...

• Important terms that will be used to build the project glossary.
• Example tasks that will be used to build acceptance tests.

Acceptance tests monitor progress and are also vital in the project sign off process. By adding usage examples, stakeholders can build a test suite that unequivocally communicates their intentions. A project glossary is a design tool to help developers deepen their knowledge of the problem space. This has long-term value, because by using the terms of the problem in the design, the program's divisions will mirror those of the underlying business model. When that business changes, the program can change in the same way. The change is thus made more easily, cutting costs over the lifetime of the code.

How are the test cases built?

A usage example that can be turned into a test is any bulleted list with a title nearby, and where every bullet contains a web browser action.

Here is a longer version of our previous example. Suppose our requirements document was called Public Share Price Use Case.doc...

When arbiter sees this section of the document it pick up the latest preceding significant text, here "Show a share price", before a list. It will scan the list for actions, and if they all fit a test case will be created. Here is the example using SimpleTest...

class PublicSharePriceUseCase extends ArbiterTestCase {
    function testShowASharePrice() {
        $this->goToHome();
        $this->click('find shares');
        $this->setField('search', 'IBM');
        $this->click('Search');
        $this->assertText('IBM share price');
    }
}

Possible actions include (bracketed terms are optional):

Go to URL

Go to home (page)

click (on) (link/button) label

set field to text

should/expect (to see) text

The developers could read the Arbiter documents to see if their code is working, but this is unlikely. The developers can instead take the generated test suite and run it separately. They can also integrate it with their existing test suites.

How are complex tests built?

Any test can also be used as a macro. If you have used word macros then Arbiter ones are similar. By naming a test as a step, Arbiter will carry out all of the steps of that test, without showing individual results, and continue the test at that point. This allows long chains of operations to be combined together.

Here is an example...

After navigating to the share page, Arbiter will click something marked as "more info" and check for the expected text.

How is the glossary built?

If a highlighted phrase such as this appears anywhere in the repository, it is marked as a glossary term. It simply has to be highlighted with respect to the surrounding text. If no definition is available then it will be marked as unavailable in the text like so: such as this(?). Also an empty entry will be placed in the master index. This master index is available online and further requests for definitions can be added or deleted there.

To fulfill a glossary definition, Arbiter will scan the repository for a paragraph title that matches the phrase apart from noise words. The paragraphs until the next title will be treated as the definition. Any content will do, even page footnotes.

The glossary is actually pervasive to Arbiter. When documents are returned from the server, if they contain any glossary words then that section of the glossary is appended to the document. The glossary is available in shortened form online as the master index, each entry being listed with just the first paragraph. When a document is uploaded or when a test fails a glossary report is included. If glossary entries appear in the text, then they are highlighted. This alerts the writer that a jargon word may have been used out of context.

The idea is that if the developers or stakeholders mark something important it is very obvious that a source of confusion exists until the phrase is defined. This is a nag factor, ensuring that neither the stakeholders nor the developers are using language that the other party does not understand.