Ambra Integration Testing

See Also: PlosTestFramework? (more for rpm testing)

Overview

This documents how to use the integration test framework at source:head/plosone/it.

The idea is that tests will have complete control of the environment. ie. install/restore/start/stop can all be done from within the test - the same way as we do drop-model/create-model for OTM tests. In addition with canned data - we sort of provide the db-unit functionality.

Structure

  • src/main - A library for loading canned data and starting and stopping services. This library is used by the tests.
  • src/it - Actual integration tests

Canned data

Creating & deploying canned data

Canned data is stored in the maven repository on gandalf. The data has the format (initially from r3333): 

data
`-- README
`-- lucene
`-- ingestion-queue
`-- ingested
`-- fedora
|   |-- objects
|   |-- datastreams
`-- mulgara (mulgara data dir)

Note that the data directory shown here is used "inline" by all services except fedora. If you are augmenting test data via runtime manipulation of the PLoS site and you want to package the new state of the data, you will need to copy the fedora/objects and fedora/datastreams directories from the fedora-2.1.1/data directory to the data directory described above.

The data directory above should be tar'ed and bzip2'ed and deployed (As of r3734) using commands like this: 

  
tar -cvf data.tar data
bzip2 data.tar
mvn -e deploy:deploy-file -DMAVEN_OPTS="-Xmx512m" -DgroupId=org.plosone -DartifactId=plosone-it-data-basic -Dversion=0.8-SNAPSHOT -Dpackaging=tbz -Dfile=data.tar.bz2 -DrepositoryId=topaz -Durl=http://gandalf.topazproject.org/maven2

See MavenInfo for deployment instructions. But briefly, you may want to be directly on gandalf as deploying large files over the network usually hang and/or break. The group should be org.plosone and the artifact should be plosone-it-data...

The README should contain some notes about the contents. eg. what users and articles etc. exist. Who is the admin user etc.

There are many archived article zips available on Merlin in dir: /var/ftp/allenpress/allentrack2plos1/

Using canned data

To use your canned data in your test, create the environment in your test as: 

Env env = new Env("install/500articles", "org.plosone:plosone-it-data-500articles:0.8");

For an example, see:

The install directory

Since data-sets can get large, the environments (Envs) should be installed in a directory that is not cleaned by mvn clean. A convention may be to use head/plosone/it/install. This should make running subsequent tests faster. But it may also create confusion compared to the way mvn clean usually works. By following the convention of installing everything under the head/plosone/it/install, the continuum builds etc. can delete that directory before starting up new integration tests.

Running tests

NOTE: PLEASE MAKE SURE /etc/topaz HAS BEEN RENAMED TO AVOID THE SERVICES FROM PICKING UP CONFIGURATION INFORMATION FROM THERE. 

mvn -Pit-helper clean install

If you want to run just one test class, add -Dtest=testname -DstopOnStart=true/false -DstopOnExit=true/false -DskipStartEnv=true/false

  • stopOnStart - stops services from a previous run or from a manual start. Default is true
  • skipStartEnv - runs the test against an environment from a previous run or from a manual start. Default is false
  • stopOnExit - stops services on exit. Default is true

Starting the environment on its own

Normally, you run the tests (and the tests load canned data and start containers) and then everything stops. However, for some kinds of tests, it may be more convenient to just start up the containers and keep them running. To do this, run: 

#!/bin/sh
if [ 0 -eq $# ]; then
  echo "Usage: $0 <path to installation. eg. 'install/basic'>"
  exit 1
fi
mvn exec:java -DEnv=$1 -Dcommand=start

Additional usage examples (originally from r3375):

eg. to reset the data (to the orginal canned-state) 

  mvn exec:java -DEnv='install/basic' -Dcommand=restore -Ddata=org.plosone:plosone-it-data-basic:0.8-SNAPSHOT

eg. to install 

  mvn exec:java -DEnv='install/basic' -Dcommand=install -Ddata=org.plosone:plosone-it-data-basic:0.8-SNAPSHOT

Logs

log4j config files used by each environment is set up in the root of its install directory. (eg. install/basic). The logs by default are configured to write to the stdout which gets redirected by cargo into an output.log file. eg install/basic/plosone-webapp/tomcat/log/output.log for the plosone webapp and similarly for mulgara.

Debugging Tests

To debug tests, add -Dmaven.surefire.debug=true to the command line. The tests should pause with a line such as "Listening for transport dt_socket at address: 5005" allowing you to connect with a remote debugger to the stated port (5005).