~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements.  See the NOTICE file
~~ distributed with this work for additional information
~~ regarding copyright ownership.  The ASF licenses this file
~~ to you under the Apache License, Version 2.0 (the
~~ "License"); you may not use this file except in compliance
~~ with the License.  You may obtain a copy of the License at
~~
~~   http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing,
~~ software distributed under the License is distributed on an
~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
~~ KIND, either express or implied.  See the License for the
~~ specific language governing permissions and limitations
~~ under the License.

Usage

  The <<<tuscany-itest-plugin>>> is associated with the <<<integration-test>>> phase of the build lifecycle.

  The plugin can be invoked directly from the command line:

+---+
mvn org.apache.tuscany.sca:tuscany-itest-plugin:test
+---+

  or can be included in the build definition for your project:
  
+---+
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.tuscany.sca</groupId>
                <artifactId>tuscany-itest-plugin</artifactId>
                <executions>
                    <execution>
                        <goals>
                            <goal>test</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
+---+

* Writing Integration Tests

  Integration tests are written as JUnit TestCases (currently only JUnit 3.8.1 is supported but other frameworks
  may be added later) that use SCA references to access services provided by the components under test. The
  references are injected into your testcase before its setUp method is called (using constructor, setter or field
  injection).

  For example, to test a component that implemented the <<<MyService>>> interface you could write:

+---+
public class ServiceTestComponent extends TestCase {

    @Reference
    public MyService service;

    public void testSomething() {
        assertEquals(result, service.doSomething);
    }
}
+---+

  This TestCase is used as a component within a SCA composite that defines the test suite
  as described in the next section. This separates TestCase's for normal unit tests from
  those that are integration tests.

  If any methods have an SCA <<<@Init>>> or <<<@Destroy>>> annotation they will be called
  before and after executing tests; if no methods are annotated in this way the normal
  JUnit <<<setUp>>> and <<<tearDown>>> methods will be called.

  If the component's scope is <<<STATELESS>>> (the default), then a new instance of the
  test component will used to run each test; if the component's scope is <<<COMPOSITE>>>
  then a single instance will be used to run all tests. The scope can be set with the
  standard SCA <<<@Scope>>> annotation.

* Defining an SCA Test Suite

  The Test Suite for your integration tests is defined by an SCA composite file that contains
  the test components written above wired to the production components for the application.
  The test components must use an implementation type of <<< <tuscany:junit> >>>.
  
  A simple way to achieve this is to use a SCDL <include> element to include the content of
  production composite in the test harness; this gives the test components access to all of
  the components and references in the production composite.

  For example, the following SCDL configures the <<<ServiceTestComponent>>> above
  to test the <<<MyServiceComponent>>> in the production composite <<<ProductionComposite>>>:

+---+
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0"
           xmlns:tuscany="http://tuscany.apache.org/xmlns/sca/2.0-alpha"
           name="PropertyTestHarnessComposite">

    <include name="ProductionComposite" scdlResource="META-INF/sca/default.scdl"/>

    <component name="testMyService">
        <tuscany:junit class="ServiceTestComponent"/>
        <reference name="service">MyServiceImpl</reference>
    </component>
</composite>
+---+

  Alternatively, the production composite can be tested as a black box by using it to
  implement a component and wiring test components to it. This allows the externally
  visible services to be tested without knowledge of the internals of the composite.

  For example, the following SCDL tests the <<<ProductionComposite>>> in this way:

+---+
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0"
           xmlns:tuscany="http://tuscany.apache.org/xmlns/sca/2.0-alpha"
           name="PropertyTestHarnessComposite">

    <component name="ProductionComponent">
        <implementation.composite name="ProductionComposite"
                                  scdlResource="META-INF/sca/default.scdl"/>
    </component>

    <component name="testMyService">
        <tuscany:junit class="ServiceTestComponent"/>
        <reference name="service">ProductionComponent</reference>
    </component>
</composite>
+---+

  The location of this test composite definition can be specified using the <<<testScdl>>>
  plugin configuration property; the default location is <<<${project.build.testOutputDirectory}/itest.scdl>>>
  which allows the <<<itest.scdl>>> source file to be placed in the test resources (<<<src/test/resources>>>).

* Test Result Output

  The test results are output using Surefire's reporting framework for integration with other test reports.
  XML and test results are stored in the normal test output directory (<<<target/surefire-reports>>>) with
  a summary displayed on the console:

+---+
[INFO] [tuscany-itest:test {execution: default}]
[INFO] Starting Tuscany...
[INFO] Deploying test SCDL from .../target/test-classes/itest.scdl
[INFO] Executing tests...

-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running testMyService
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.002 sec

Results :
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

[INFO] Stopping Tuscany...
+---+