-------------------------------------------------------------------
                 Fedora 3.5-SNAPSHOT - Unreleased
-------------------------------------------------------------------
This is a full source code release of Fedora.  Before using this
software, you must read and agree to the license, found under
resources/doc/license/license.html.  Documentation can be found for
online browsing or download at http://fedora-commons.org/go/fcr30

Building Fedora
===============
To build the executable installer, make sure you have maven2
installed and enter the following:

  mvn install

This generates fcrepo-installer-VERSION.jar, which can be found in
fcrepo-installer/target.

This also runs all unit and integration tests.  If you wish to build the
installer without running the integration tests see below.

Running Unit Tests
=====================

  mvn install -Dintegration.test.skip=true
  
This generates the installer jar as above, running the unit tests, 
but without running the integration tests.

Running System Tests
====================
The system tests consist of functional "black box" tests to be
executed against a running Fedora server.  These tests are divided
into top-level suites, where each suite is intended to be run with
the Fedora server configured in a specific way.  By default, maven
will install and run a properly configured Fedora instance for each
plausible system test configuration.

  [configA]
    When running this suite, the server shall be configured
    with API-A authentication turned OFF, SSL required for API-M,
    XACML enabled, and the Resource Index disabled.

  [configB]
    When running this suite, the server shall be configured
    with API-A authentication turned ON, with the
    Resource Index, REST api, and Messaging modules enabled.
    
  [configC]
    When running this suite, the server shall be configured
    with API-A authentication turned ON, with the
    Resource Index, REST api, and fesl authZ enabled.  If tests are
    being run against an externally-deployed Fedora it is necessary
    to set the environment variable PEP_NOCACHE=true before starting
    the Fedora instance, or some tests will fail.
    
  [configQ]
    When running this suite, the server shall be configured
    with the default options provided by 'quick install'.
    It can be used to verify the successful installation of 'quick install'.
    
These tests do not depend on external hosts and can therefore be
run without external network access.

Installation properties files are supplied in the 
fcrepo-integrationtest-core/src/main/resources/config
folder if you wish to manually configure and run an instance
of Fedora to test against.  You will need to customise folder locations 
and DNS names to suit your own installation.  These files can be supplied
as arguments to the installer jar file to simplify setting up test scenarios.

In order to use an externally-run fedora instance, you must define the
-Dfedora.home=${FEDORA_HOME} system property.  If that is set, maven will not
attempt to install or run its own Fedora instance, and will assume that 
a running and properly configured instance is available.

All applicable integration/system test suites will be run through any of the following:
mvn verify
mvn install
mvn deploy

Specific test suites can be disabled by defining system properties
such as: 
-DconfigA=false
-DconfigB=false, etc.  
multiple suites can be disabled at one time

A single integration test suite can be run by defining system properties
such as 
-Dconfig=A (run only configA)
-Dconfig=B (run only configB)
(etc)

By default, each test will run using the demo objects in
FOXML format.  To run the same tests using the demo objects
in METS, Atom, or Atom Zip format, add one of the following to 
the line above:

  -Ddemo.format=mets
  -Ddemo.format=atom
  -Ddemo.format=atom-zip
  
To run individual integration/system tests, supply the name of the test
as a value of the property 'it.test'
  
 mvn verify -Dit.test=org.fcrepo.test.api.TestManagedDatastreams
 
This needs to be run from within the fcrepo-integrationtest directory in
order to correctly resolve the class name of the test.

There are some system tests that are not included in the system
test suites due to the time required to execute the test,
the following tests fall into that category:

  [org.fcrepo.test.integration.TestLargeDatastreams]
    This test adds a 5GB datastream through API-M, then 
    retrieves it via API-A and API-A-Lite. When running 
    this test, the server should be configured to allow
    non-SSL access to API-M and API-A. This test has no
    dependencies on external hosts and can therefore be 
    run without external internet access.
  
    
    mvn verify -Dconfig=[A|Q] -Dit.test=org.fcrepo.test.integration.TestLargeDatastreams

Running system tests with an alternate host or webapp context
=============================================================
By default, integration tests assume Fedora is running at
http://localhost:8080/fedora/.  A different server port may be
chosen with no consequence.

However, if the fedora server uses an alternate app
server context (i.e. not /fedora), (or if you want integration tests to 
run as such) you must set the system property 
-Dfedora.appServerContext=${WEBAPP_NAME}

Additionally, if your test instance of Fedora is not on the same 
host from which you are running the tests, you must manually 
edit or remove the deny-apim-if-not-localhost.xml policy before
testing.