org.geotools.test

Class OnlineTestCase

Object

Assert

TestCase

OnlineTestCase

All Implemented Interfaces:

Test

public abstract class OnlineTestCase
extends TestCase

Test support for test cases that require an "online" resource, such as an external server or database.

Online tests work off of a "fixture". A fixture is a properties file which defines connection parameters for some remote service. Each online test case must define the id of the fixture is uses with getFixtureId().

Fixtures are stored under the users home directory, under the ".geotools" directory. Dots "." in the fixture id represent a subdirectory path under this configuration file directory. For example, a fixture id a.b.foo would be resolved to .geotools/a/b/foo.properties.

In the event that a fixture does not exist, the test case is aborted.

Online tests connect to remote / online resources. Test cases should do all connection / disconnection in the connect() and disconnect() methods.

The default behaviour of this class is that if connect() throws an exception, the test suite is disabled, causing each test to pass without being run. In addition, exceptions thrown by disconnect() are ignored. This behaviour allows tests to be robust against transient outages of online resources, but also means that local software failures in connect() or disconnect() will be silent.

To have exceptions thrown by connect() and disconnect() cause tests to fail, set skip.on.failure=false in the fixture property file. This restores the traditional behaviour of unit tests, that is, that exceptions cause unit tests to fail.

Since:

2.4

Author:

Justin Deoliveira, The Open Planning Project, Ben Caradoc-Davies, CSIRO Earth Science and Resource Engineering

Field Summary

Fields

Modifier and Type	Field and Description
protected Properties	fixture The test fixture, null if the fixture is not available.
protected static Map<String,Boolean>	found A static map which tracks which fixture files can not be found.
protected static Map<String,Boolean>	online A static map which tracks which fixtures are offline.
static String	ONLINE_TEST_PROFILE System property set to totally disable any online tests
static String	SKIP_ON_FAILURE_DEFAULT The default value used for SKIP_ON_FAILURE_KEY if it is not present.
static String	SKIP_ON_FAILURE_KEY The key in the test fixture property file used to set the behaviour of the online test if connect() fails.
protected boolean	skipOnFailure Flag that determines effect of exceptions in connect/disconnect.

Constructor Summary

Constructors

Constructor and Description
OnlineTestCase()

Method Summary

Modifier and Type	Method and Description
protected void	connect() Connection method, called from setUp().
protected Properties	createExampleFixture() Allows test to create a sample fixture for users.
protected Properties	createOfflineFixture() Allows tests to create an offline fixture in cases where the user has not specified an explicit fixture for the test.
protected void	disconnect() Disconnection method, called from tearDown().
protected abstract String	getFixtureId() The fixture id for the test case.
protected boolean	isOnline() Tests if external resources needed to run the tests are online.
void	run(TestResult result) Override which checks if the fixture is available.
protected void	setUp() Loads the test fixture for the test case.
protected void	setUpInternal() Method for subclasses to latch onto the setup phase.
protected void	tearDown() Tear down method for test, calls through to disconnect() if the test is active.
protected void	tearDownInternal() Method for subclasses to latch onto the teardown phase.

Methods inherited from class TestCase

assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertFalse, assertFalse, assertNotNull, assertNotNull, assertNotSame, assertNotSame, assertNull, assertNull, assertSame, assertSame, assertTrue, assertTrue, countTestCases, createResult, fail, fail, failNotEquals, failNotSame, failSame, format, getName, run, runBare, runTest, setName, toString

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

ONLINE_TEST_PROFILE

public static final String ONLINE_TEST_PROFILE

System property set to totally disable any online tests

See Also:

Constant Field Values

SKIP_ON_FAILURE_KEY

public static final String SKIP_ON_FAILURE_KEY

The key in the test fixture property file used to set the behaviour of the online test if connect() fails.

See Also:

Constant Field Values

SKIP_ON_FAILURE_DEFAULT

public static final String SKIP_ON_FAILURE_DEFAULT

The default value used for SKIP_ON_FAILURE_KEY if it is not present.

See Also:

Constant Field Values

online

protected static Map<String,Boolean> online

A static map which tracks which fixtures are offline. This prevents continually trying to run a test when an external resource is offline.

found

protected static Map<String,Boolean> found

A static map which tracks which fixture files can not be found. This prevents continually looking up the file and reporting it not found to the user.

fixture

protected Properties fixture

The test fixture, null if the fixture is not available.

skipOnFailure

protected boolean skipOnFailure

Flag that determines effect of exceptions in connect/disconnect. If true (the default), exceptions in connect cause the the test to be disabled, and exceptions in disconnect to be ignored. If false, exceptions will be rethrown, and cause the test to fail.

Constructor Detail

OnlineTestCase

public OnlineTestCase()

Method Detail

run

public void run(TestResult result)

Override which checks if the fixture is available. If not the test is not executed.

Specified by:

run in interface Test

Overrides:

run in class TestCase

setUp

protected final void setUp()
                    throws Exception

Loads the test fixture for the test case.

The fixture id is obtained via getFixtureId().

Overrides:

setUp in class TestCase

Throws:

Exception

setUpInternal

protected void setUpInternal()
                      throws Exception

Method for subclasses to latch onto the setup phase.

Throws:

Exception

tearDown

protected final void tearDown()
                       throws Exception

Tear down method for test, calls through to disconnect() if the test is active.

Overrides:

tearDown in class TestCase

Throws:

Exception

tearDownInternal

protected void tearDownInternal()
                         throws Exception

Method for subclasses to latch onto the teardown phase.

Throws:

Exception

isOnline

protected boolean isOnline()
                    throws Exception

Tests if external resources needed to run the tests are online.

This method can return false to indicate the online resources are not up, or can simply throw an exception.

Returns:

True if external resources are online, otherwise false.

Throws:

Exception - Any errors that occur determining if online resources are available.

connect

protected void connect()
                throws Exception

Connection method, called from setUp().

Subclasses should do all initialization / connection here. In the event of a connection not being available, this method should throw an exception to abort the test case.

Throws:

Exception - if the connection failed.

disconnect

protected void disconnect()
                   throws Exception

Disconnection method, called from tearDown().

Subclasses should do all cleanup here.

Throws:

Exception - if the disconnection failed.

createOfflineFixture

protected Properties createOfflineFixture()

Allows tests to create an offline fixture in cases where the user has not specified an explicit fixture for the test.

Note, that this should method should on be implemented if the test case is created of creating a fixture which relies soley on embedded or offline resources. It should not reference any external or online resources as it prevents the user from running offline.

createExampleFixture

protected Properties createExampleFixture()

Allows test to create a sample fixture for users.

If this method returns a value the first time a fixture is looked up and not found this method will be called to create a fixture file with teh same id, but suffixed with .template.

getFixtureId

protected abstract String getFixtureId()

The fixture id for the test case.

This name is hierarchical, similar to a java package name. Example: "postgis.demo_bc".

Returns:

The fixture id.