Getting Started

1. Installing DbFit

DbFit needs the Java Runtime Environment to run - it can be downloaded from the Oracle's Java homepage.

Download DbFit

Unpack dbfit-complete-XXX.zip somewhere on your disk, and run startFitnesse.bat (or startFitnesse.sh on Linux). When FitNesse starts, you should see a command window with this message:

FitNesse (v20121220) Started...
        port:              8085
        root page:         fitnesse.wiki.FileSystemPage at ./FitNesseRoot
        logger:            none
        authenticator:     fitnesse.authentication.PromiscuousAuthenticator
        page factory:      fitnesse.responders.PageFactory
        page theme:        fitnesse_straight
        page version expiration set to 0 days.

Open http://localhost:8085/ and you should see the welcome page. FitNesse is up and running. When you want to shut it down later, just press Ctrl+C in the command window (or close the command window).

FitNesse.bat failed. What's wrong?

Read the exception from the command window. If the error mentions versions, check that you have Java 5 or higher installed and that the correct version is being executed when you run java.exe. Run java.exe -version from a command window to see which version of Java is being executed by default. You can run FitNesse with a different Java version either by pointing to the correct JRE in the system executable path (right-click My Computer, select Properties, then go to the Advanced tab, click Environment Variables, and edit the Path variable), or by entering the full path to a different java.exe in startFitnesse.bat.

If the error report states that there is a security problem or the port is unavailable, enter a different port number in startFitnesse.bat and try again.

Let’s run a quick test to make sure that you have everything set up correctly and that FitNesse can connect to your test database.

2. Creating a new test page

Open http://localhost:8085/HelloWorldTest in your browser. You should see an editor - this is where we’ll create our new test page.

Note Notice that the page name is a CamelCase word.

In FitNesse, all page names have to start with a capital letter, have at least one more capital letter, and all capital letters have to be separated by at least one lowercase letter. FitNesse is really strict about that. This convention causes a lot of headaches for FitNesse newbies, but after a while you'll get used to it. Here are some good page names:

HelloWorld
TestFluxCapacitor
IsPaymentWorkingCorrectly

Here are some page names that will get you in trouble:

helloworld (no capital letters)
Testfluxcapacitor (just one capital letter)
isPaymentWorkingCorrectly (starts with a lowercase letter)
TestFCapacitor (two consecutive capital letters)

3. Setting up the environment

In order to load the DbFit extension into FitNesse, your test pages have to load the correct libraries. Replace the contents of the big textbox with the following:

!path lib/*.jar

4. Connecting to the database

DbFit requires two commands to connect to the database. The first line specifies the database type (or test type), and the second defines connection properties. These two lines will typically be the first on every test page. Here is how to connect to a MySQL database:

!|dbfit.MySqlTest|

!|Connect|localhost|dbfit_user|password|dbfit|

Notice the MySqlTest in the first line above. That tells DbFit which type of database driver to use. For SQL Server 2005 and later, you should use SqlServerTest. For MySql use MySqlTest. For Oracle, use OracleTest. For Db2, use DB2Test. For Derby (JavaDB), use DerbyTest.

Notice how each command starts with an exclamation mark (!), followed by a pipe symbol (|). Command arguments are then separated by the pipe symbol as well. In FitNesse, tables are used to describe commands, tests, inputs and expected results (you will see the table when the page is saved). In the FitNesse wiki syntax, tables are described simply by separating cells with the pipe symbol. The exclamation mark before the first row of the table is optional, and tells FitNesse not to apply any smart formatting to table contents.

5. Testing a simple query

Now let’s write a simple query test. We will send a request to the database, pull out the result set, and compare it with our expectations. In DbFit, that is done with the Query command. The second cell of the first table row, after the Query keyword, should contain the query we are executing. The second row then contains the result set structure — names of the columns that we want to inspect. You don’t have to specify the full result set here, just the columns that are interesting for a particular test. All rows after that contain expected results. Query disregards result set order — if the order is important you can use OrderedQuery. Here is a simple MySql query:

!|Query| select 'test' as x|
|x|
|test|

The same syntax should work for SQLServer. For Oracle, use this table:

!|Query| select 'test' as x from dual|
|x|
|test|

6. Running the test

Now, click Save. FitNesse will create a new page and display it in your browser. Click on the Test button to make FitNesse run the test. You should see a page telling you that the test passed.

Learn about more DbFit commands in the Reference docs.

DbFit