~~ 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.
Examples
~~~~~~~~

* Interface

  Test execution is done via simple maven CLI:

+------------------+
mvn verify
+------------------+

* A typical use case for iTest.

  When integration/system tests are getting executed in iTest environment the
  following two pieces need to be present:

** a test artifact:

    a self-contained archive (such as jar file available via Maven) includes
    test code (compiled Java classes, helper scripts, test data, golden files)

    Typically, Maven artifact has a manifest which declares the artifact
    group, name, and version. Using this triplet an artifact can be identified
    for use in upstream projects.

    Test artifact is typically coming as a by-product of a software component's
    build. E.g. Apache Pig project produces a test artifact called
    pigsmoke-0.9.0-SNAPSHOT
    (as in {{{http://repository.apache.org/snapshots/org/apache/pig/pigsmoke/0.9.0-SNAPSHOT/}this location}})
    can be used for testing Pig component of Hadoop ecosystem.

** starter project (test suite)

    this is (typically) a maven pom file which declares required dependencies
    on test artifact(s) and defines additional optional steps to prepare
    environment where the test scenarios will be executed.

    In the particular example of Pig's smoke tests artifact, the starter has to
    declare dependency to it

+-----------------------------+
<dependency>
  <groupId>org.apache.pig</groupId>
  <artifactId>pigsmoke</artifactId>
  <version>0.9.0-SNAPSHOT</version>
</dependency>
+-----------------------------+

    Pig artifact needs to be there too:

+-----------------------------+
<dependency>
  <groupId>org.apache.pig</groupId>
  <artifactId>pig</artifactId>
  <version>0.9.0-SNAPSHOT</version>
</dependency>
+-----------------------------+

    Also, Pig needs to have Hadoop client code available. Version of hadoop
    client jar really depends on the version of the cluster the tests are executed
    against:

+-----------------------------+
<dependency>
  <groupId>org.apache.hadoop</groupId>
  <artifactId>hadoop-core</artifactId>
  <version>0.20.2-SNAPSHOT</version>
</dependency>
+-----------------------------+


* Putting it all together

  As you can see in the {{{https://svn.apache.org/repos/asf/incubator/bigtop/trunk/test/suites/}suites}}
  we are using Maven failsafe plugin to execute tests in the integration testing
  phase of a maven project lifecycle.

  One of the issues with this plugin is that it requires a presence of a physical
  files somewhere on the disk in order to run appropriate tests (which might
  be included to the classpath from jar files). To avoid having same class files
  included from jar files and from disk files iTest allows to 'touch' test
  class files in the location where failsafe will be looking for them, however
  ones from jars found in the classpath will be executed.

  You can see this step being done in the toplevel
  {{{https://svn.apache.org/repos/asf/incubator/bigtop/trunk/test/suites/common/pom.xml}pom.xml}}
  file in the configuration section of <<<org.codehaus.groovy.maven>>> plugin

  iTest provides a convenient method of unpacking data files included
  into test artifacts (if needed). It is can be done from the code of the tests
  or from the project pom file (look for "unpack" goal in the example above).