Commit 679dc22f authored by Daniel Bluhm's avatar Daniel Bluhm
Browse files

Add READMEs


Signed-off-by: Daniel Bluhm's avatarDaniel Bluhm <bluhmdj@ornl.gov>
parent b1dcd0a8
......@@ -9,15 +9,19 @@ using the `@Persisted` annotation.
- MongoDB instance running locally or accessible by host name and port to the
test runner.
**Environment Variables:**
### Configuration
- `MONGO_HOST` - Host name of MongoDB instance. Defaults to `localhost`.
- `MONGO_PORT` - Port MongoDB is running on on host. Defaults to `27017`.
- `MONGO_DB` - The database to use for testing. Defaults to `test`.
**Property file location:** `$TEST_DATA_DIR/mongo.properties`
### Running tests
**Properties:**
#### Running with local MongoDB
- `host` - Host name of MongoDB instance. Defaults to `localhost` if unset.
- `port` - Port MongoDB is running on on host. Defaults to `27017` if unset.
- `database` - The database to use for testing. Defaults to `test` if unset.
## Running tests
### Running with local MongoDB
To run these tests, you will need a running instance of MongoDB. A quick method
to get a running instance is to launch a container using docker or podman (if
......@@ -39,14 +43,21 @@ Then you can execute tests from this directory with the standard:
$ mvn clean test
```
#### Running with remote MongoDB
### Running with remote MongoDB
If there is an already running instance of MongoDB available, place a property
file like the following in your test data directory with your values filled in:
```properties
host=mymongoserver
port=27017
database=testing_db
```
If there is an already running instance of MongoDB available, use environment
variables to configure the tests to use that instance:
If your test data directory is not `$HOME/ICETests`, you can set it using the
`TEST_DATA_PATH` environment variable:
```sh
$ MONGO_HOST=mymongoserver \
MONGO_PORT=27017 \
MONGO_DB=testing_db \
$ TEST_DATA_PATH=/tmp/ICETests \
mvn clean test
```
\ No newline at end of file
......@@ -48,6 +48,21 @@ class TestElementPersistenceHandlerTest {
*/
public static final String CONFIG = "mongo.properties";
/**
* Default hostname of MongoDB instance.
*/
public static final String DEFAULT_HOST = "localhost";
/**
* Default port of MongoDB instance.
*/
public static final String DEFAULT_PORT = "27017";
/**
* Default database to use in testing.
*/
public static final String DEFAULT_DB = "test";
/**
* Connection to MongoDB.
*/
......@@ -60,15 +75,12 @@ class TestElementPersistenceHandlerTest {
/**
* Set up our test environment.
*
* Mongo host, port, and database name are retrieved from environment or the
* defaults of "localhost", "27017", and "test" are used, respectively.
*/
public TestElementPersistenceHandlerTest() {
TestConfig config = TestConfig.from(CONFIG);
String host = config.getProperty("host", "localhost");
String port = config.getProperty("port", "27017");
String database = config.getProperty("database", "test");
String host = config.getProperty("host", DEFAULT_HOST);
String port = config.getProperty("port", DEFAULT_PORT);
String database = config.getProperty("database", DEFAULT_DB);
this.db = MongoClients.create(
String.format("mongodb://%s:%s", host, port)
).getDatabase(database);
......
Eclipse ICE Testing utilities - Data and Config Retrieval
=========================================================
This test utility module contains the following utilities for data and
configuration retrieval:
- `TestDataPath` - Construct paths to the test data directory and other helpful
methods.
- `TestConfig` - Load a property file from the test data directory.
## `TestDataPath` Usage Example
For the full API, see the JavaDocs for `TestDataPath`. Below are a few general
examples.
### Constructing paths to test data
Consider the following example of manually loading data from ICE 2:
```java
// Local Declarations
String separator = System.getProperty("file.separator");
String userDir = System.getProperty("user.home") + separator
+ "ICETests" + separator + "datastructuresData";
String txtFilePath = userDir + separator + "txtResource.txt";
String csvFilePath = userDir + separator + "csvResource.csv";
```
Using `TestDataPath` the above becomes:
```java
TestDataPath dataPath = new TestDataPath();
Path txtFilePath = dataPath.resolve("datastructuresData/txtResource.txt");
Path csvFilePath = dataPath.resolve("datastructuresData/csvResource.csv");
```
Note the usage of `/` as the name separator; this will typically be correctly
converted into the separator appropriate for your platform but it may be safer
to perform a double resolve
(`dataPath.resolve("datastructuresData").resolve("csvResource.csv")`) or
handle separators yourself directly.
### Using a different test data directory
By default, the test data directory is set to `$HOME/ICETests` (`$HOME` as
returned by `System.getProperty("user.home")`. To use a different directory,
use the `TEST_DATA_PATH` environment variable. For example, if running
integration tests from the `org.eclipse.ice.tests.integration` package:
```sh
$ TEST_DATA_PATH=/tmp/ICETestData/ mvn clean test
```
This will search for test data and configuration files within the
`/tmp/ICETestData` directory.
## `TestConfig` Usage Example
For the full API, see the JavaDocs for `TestConfig`. Below are a few general
examples.
### Using static method `from`
For convenience, a static method is provided for loading a `TestConfig` directly
from a file:
```java
TestConfig config = TestConfig.from("mongo.properties");
String host = config.getProperty("host", "localhost");
String port = config.getProperty("port", "27017");
String database = config.getProperty("database", "test");
```
It is important to note that `TestConfig.load` and `TestConfig.from` will
quietly fail (a warning is logged) when the file does not exist or is unreadable
as a property file. This is to support the pattern shown above of allowing for
defaults to be loaded statically from code when no configuration file is
present.
If configuration file non-existence should be a hard fail condition, use
`TestDataPath.exists` to check for the file prior to loading.
### Using `load`
The same example used above without the use of `from`:
```java
TestDataPath dataPath = new TestDataPath();
TestConfig config = new TestConfig(dataPath);
config.load("mongo.properties");
String host = config.getProperty("host", "localhost");
String port = config.getProperty("port", "27017");
String database = config.getProperty("database", "test");
```
This usage may be helpful for the scenario described above of file non-existence
being an error condition:
```java
TestDataPath dataPath = new TestDataPath();
TestConfig config = new TestConfig(dataPath);
if (!dataPath.exists("mongo.properties") {
fail("mongo.properties missing!");
}
config.load("mongo.properties");
String host = config.getProperty("host");
String port = config.getProperty("port");
String database = config.getProperty("database");
```
\ No newline at end of file
......@@ -42,7 +42,7 @@ public class TestDataPath {
/**
* Environment variable for test data directory location.
*/
static final String TEST_DATA_DIR_ENV_VAR = "TEST_DATA_DIR";
static final String TEST_DATA_PATH_ENV_VAR = "TEST_DATA_PATH";
/**
* Test data directory.
......@@ -79,7 +79,7 @@ public class TestDataPath {
* loaded.
*/
private Path determineTestDataDirectory(Map<String, String> env) {
String alternateTestDataDir = env.get(TEST_DATA_DIR_ENV_VAR);
String alternateTestDataDir = env.get(TEST_DATA_PATH_ENV_VAR);
if (alternateTestDataDir == null) {
return fs.getPath(DEFAULT_TEST_DATA_DIR.toString());
} else {
......
......@@ -47,6 +47,15 @@ class TestDataPathTest {
return new TestDataPath(fs, env);
}
@Test
void testPlatformIndependence() {
FileSystem fs = Jimfs.newFileSystem(Configuration.windows());
TestDataPath data = new TestDataPath(fs, Map.of(
TestDataPath.TEST_DATA_PATH_ENV_VAR, "test"
));
assertEquals("test\\test\\test.txt", data.resolve("test/test.txt").toString());
}
@Test
void testResolve() throws IOException {
TestDataPath data = inMemTestDataPath(null);
......@@ -60,7 +69,7 @@ class TestDataPathTest {
void testResolveWithOverridenDefault() throws IOException {
final Path alt = Path.of("/home/test/test_data");
TestDataPath data = inMemTestDataPath(
Map.of(TestDataPath.TEST_DATA_DIR_ENV_VAR, alt.toString())
Map.of(TestDataPath.TEST_DATA_PATH_ENV_VAR, alt.toString())
);
assertEquals(
alt.resolve("test").toString(),
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment