THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
...
In the past, tests were numbered sequentially (it001,it002, etc). This becomes problematic because it's not always obvious what the issue is related to the test. More importantly, it's hard to create and submit sequential tests via patches because non-committers have no way to reserve the next number. This leads to extra work to apply the patch.
New New tests should be named using the Jira Issue JIRA issue id along with a meaningful name. This name should typically be the subject of the issue or a subset. It should be informative of the issue but not excessively long. Therefore a good name would be: mng1234-groupIdOrderIsBackwards.This name is typically used in several places of the test: the folder MavenITmng1234groupIdOrderIsBackwardsTest. The corresponding resource directory for this test in core-integrationit-testssuite/src/test/resources/ that contains the sample project along with the name of the junit class used to invoke the sample project and check the results.
Sample IT Project
would simply be named mng-1234, i.e. without the description to keep the path short.
Sample IT Project
A sample project A sample project has been created to aid in IT test creation. It can be retrieved using svn hereor Subversion from our source repository or directly viewed with your browser herevia our SVN view.
Sample IT Archetype Archetype
This project has also been converted into an archetype to make it even easier to use. (NOTE: This is currently not deployed and bugs prevent this from being usable right now. Use the Sample IT project for now and skip this section -Brianf 8/8/07)
Using ArchetypeNG To create a sample from the archetype
| Wiki Markup |
|---|
It would be helpful to review the archetypeNG plugin tutorial here: \[insert url of site when it lands at apache\] |
The maven-archetypeng-plugin is currently a snapshot. You will need to add the snapshot repository to your settings to be able to retreive the plugin and the archetype (when it gets deployed).
| No Format |
|---|
<settings>
...
<profiles>
<profile>
<id>maven-snapshots</id>
<repositories>
<repository>
<id>Maven Snapshots</id>
<url>http://people.apache.org/repo/m2-snapshot-repository</url>
<snapshots>
<enabled>true</enabled>
</snapshots>
<releases>
<enabled>false</enabled>
</releases>
</repository>
<repositories>
<profile>
<profiles>
<!--need to activate my profile unless I want to type 'mvn -Pmaven-snapshots' all the time-->
<activeProfiles>
<activeProfile>maven-snapshots</activeProfile>
</activeProfiles>
</settings>
|
The archetypeNG plugin maintains a list of known archetype groups for interactive prompting. The next step is to add the IT group:
ARCHETYPE-82: You must manually create archetype.xml in your $HOME/.m2 folder and it must minimally contain the following:
| Panel |
|---|
<?xml version="1.0" encoding="UTF-8"?><archetype-registry> |
| No Format |
|---|
mvn archetypeng:add-groups -Dgroups=org.apache.maven.its
|
Successful output:
It would be helpful to review the archetype plugin documentation here: http://maven.apache.org/plugins/maven-archetype-plugin/
The Archetype Plugin doesn't currently know about this archetype, so we created a catalog file to be used.
| No Format |
|---|
mvn archetype:generate -DarchetypeCatalog=http://docs.codehaus.org/download/attachments/1835439/archetype-catalog.xml
|
| No Format |
|---|
$ mvn archetype:generate -DarchetypeCatalog=http://docs.codehaus.org/download/attachments/1835439/archetype-catalog.xml
[INFO] Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'archetype'.
[INFO] ------------------------------------------------------------------------
[INFO] Building Maven Default Project
[INFO] task-segment: [archetype:generate] (aggregator-style)
[INFO] ------------------------------------------------------------------------
[INFO] Preparing archetype:generate
[INFO] No goals needed for project - skipping
[INFO] Setting property: classpath.resource.loader.class => 'org.codehaus.plexus.velocity.ContextClassLoaderResourceLoader'.
[INFO] Setting property: velocimacro.messages.on => 'false'.
[INFO] Setting property: resource.loader => 'classpath'.
[INFO] Setting property: resource.manager.logwhenfound => 'false'.
[INFO] [archetype:generate]
Choose archetype:
1: remote -> maven-it-sample-archetype (Archetype for creating a Maven 2 Integration Test)
Choose a number: (1): 1
[INFO] snapshot org.apache.maven.its:maven-it-sample-archetype:1.0-SNAPSHOT: checking for updates from maven-it-sample-archetype-repo
Downloading: http://people.apache.org/repo/m2-snapshot-repository/org/apache/maven/its/maven-it-sample-archetype/1.0-SNAPSHOT/maven-it-sample-archetype-1.0-20080303.190914-2.jar
9K downloaded
Define value for groupId: : org.apache.maven.its
Define value for artifactId: : my-it
Define value for version: : 1
Define value for package: : org.apache.maven.it
Confirm properties configuration:
groupId: org.apache.maven.its
artifactId: my-it
version: 1
package: org.apache.maven.it
Y: : Y
[WARNING] org.apache.velocity.runtime.exception.ReferenceException: reference : template = archetype-resources/src/test/resources/mng-xxxx-descriptionOfProblem/checkstyle-test/pom.xml [line 42,column 26] : ${project.build.directory} is not a valid reference.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 44 seconds
[INFO] Finished at: Mon Mar 03 19:13:41 GMT 2008
[INFO] Final Memory: 10M/28M
[INFO] ------------------------------------------------------------------------
|
The project will be created in a subfolder of your current directory with the name you chose for the artifact. (my-it in the above example).
Tour of the Sample Project
The sample IT project contains the following files:
| No Format |
|---|
| pom.xml
|
\---src
\---test
+---java
| \---org
| \---apache
| \---maven
| \---it
| | MavenITmngXXXXDescriptionOfProblemTest.java
|
\---resources
\---mng-xxxx
| pom.xml
| readme.txt
|
+---checkstyle-assembly
| | pom.xml
| |
| +---src
| \---main
| \---resources
| rule_set.xml
| stc_checks.xml
|
|
|
\---checkstyle-test
| pom.xml
|
\---src
\---main
\---java
Class.java
|
The directory src/test/java/ contains a junit file used to execute the sample project. It is heavily commented to guide you along. Stop here and Take a look before continuing.
The directory src/test/resources contains a sample project tree that will be invoked to test our condition. The sample consists of a few modules, first an extension (checkstyle-assembly) that is jarred up and installed into the repository. Then a second invocation is made on a project that uses the extension (checkstyle-test)
The sample IT project uses the simplest method of using the verifier, that is the sample build fails if the test should fail. More complicated ITs can be created with beanshell scripts to check complex conditions. (Example Needed) (Link to verifier docs)
Once your IT is complete, you should be able to execute it:
| No Format |
|---|
>mvn test
[INFO] Scanning for projects...
[INFO] ----------------------------------------------------------------------------
[INFO] Building Maven Integration Tests
[INFO] task-segment: [test]
[INFO] -- |
| No Format |
E:\svn\Maven\atest>mvn archetypeng:add-groups -Dgroups=org.apache.maven.its Using maven.home=c:\Program Files\maven2\bin\\.. [INFO] Scanning for projects... [INFO] Searching repository for plugin with prefix: 'archetypeng'. [INFO] ---------------------------------------------------------------------------- [INFO] Building Maven Default Project [INFO] task-segment: [archetypeng:add-groups] (aggregator-style) [INFO] ----------------------------------------------------------- [INFO] [resources:resources] [INFO] Using default encoding to copy filtered resources. [INFO] [compiler:compile] [INFO] No sources to compile [INFO] [resources:testResources] [INFO] Using default encoding to copy filtered resources. [INFO] [compiler:testCompile] [INFO] Compiling 1 source file to E:\svn\Maven\maven-it-tests\test\artifact\target\test-classes [INFO] [surefire:test] [INFO] Surefire report directory: E:\svn\Maven\maven-it-tests\test\artifact\target\surefire-reports --------------------------------------------- [INFO] [archetypeng:add-groups] [INFO] --------- T E S T S --------------------------------------------------------------- [INFO] BUILD SUCCESSFUL [INFO] ------------------------- Running org.apache.maven.it.MavenITmngXXXXDescriptionOfProblemTest mngXXXXDescriptionOfProblem(testitMNGxxxx).. OK Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 16.802 sec Results : Tests run: 1, Failures: 0, Errors: 0, Skipped: 0 [INFO] ----------------------------------------------- [INFO] Total time: 2 seconds [INFO] Finished at: Wed Aug 08 21:58:57 EDT 2007 [INFO] Final Memory: 5M/10M [INFO] -------------------------- [INFO] BUILD SUCCESSFUL [INFO] ---------------------------------------------- |
Now you can create the archetype project:
| No Format |
|---|
mvn archetype:create
|
...
Tour of the Sample Project
The sample IT project contains the following files:
| No Format |
|---|
| pom.xml | \---src \---test +---java | \---org | \---apache | \---maven | \---integrationTests | | MavenITmngXXXXDescriptionOfProblemTest.java | \---resources \---mng-xxxx-descriptionOfProblem | pom.xml | readme.txt | +---checkstyle-assembly | | pom.xml | | | +---src | \---main | \---resources | rule_set.xml | stc_checks.xml | | | \---checkstyle-test | pom.xml | \---src \---main \---java Class.java |
src/test/java/contains a junit file used to execute the sample project. It is heavily commented to guide you along. Stop here and Take a lookbefore continuing.
src/test/resources contains a sample project tree that will be invoked to test our condition. The sample consists of a few modules, first an extension (checkstyle-assembly) that is jarred up and installed into the repository. Then a second invocation is made on a project that uses the extension (checkstyle-test)
The sample IT project uses the simplest method of using the verifier, that is the sample build fails if the test should fail. More complicated ITs can be created with beanshell scripts to check complex conditions. (Example Needed) (Link to verifier docs)
Once your IT is complete, you should be able to execute it:
---------------
[INFO] Total time: 25 seconds
[INFO] Finished at: Wed Aug 08 22:47:44 EDT 2007
[INFO] Final Memory: 4M/10M
[INFO] ------------------------------------------------------------------------
|
Submitting your IT Test
Now that your IT is complete, create a zip, tgz or some other *normal* archive of your test and attach it to your JIRA issue.
If you are a Maven committer, read the next section to see how to integrate your test into the core, or to apply someone else's test.
Integrating an IT into the core-integration-tests
First, check out the core-it-suite
The sample project maps directly to the core-it-suite structure. Assuming the test has been named uniquely, you can copy the contents of src/test directly over to core-it-suite (don't copy from the root or you'll overwrite the POM).
| No Format |
|---|
/cygdrive/e/svn/Maven/maven-it-tests/core-it-suite
$ cp ../test/artifact/src . -R -v
`../test/artifact/src/test/java/org/apache/maven/it/MavenITmngXXXXDescriptionOfProblemTest.java' -> `./src/test/java/org/apache/maven/it/MavenITmngXXXXDescriptionOfProblemTest.java'
`../test/artifact/src/test/resources/mng-xxxx/checkstyle-assembly/pom.xml' -> `./src/test/resources/mng-xxxx/checkstyle-assembly/pom.xml'
`../test/artifact/src/test/resources/mng-xxxx/checkstyle-assembly/src/main/resources/rule_set.xml' -> `./src/test/resources/mng-xxxx/checkstyle-assembly/src/main/resources/rule_set.xml'
`../test/artifact/src/test/resources/mng-xxxx/checkstyle-assembly/src/main/resources/stc_checks.xml' -> `./src/test/resources/mng-xxxx/checkstyle-assembly/src/main/resources/stc_checks.xml'
`../test/artifact/src/test/resources/mng-xxxx/checkstyle-assembly/target/classes/rule_set.xml' -> `./src/test/resources/mng-xxxx/checkstyle-assembly/target/classes/rule_set.xml'
`../test/artifact/src/test/resources/mng-xxxx/checkstyle-assembly/target/classes/stc_checks.xml' -> `./src/test/resources/mng-xxxx/checkstyle-assembly/target/classes/stc_checks.xml'
`../test/artifact/src/test/resources/mng-xxxx/checkstyle-test/pom.xml' -> `./src/test/resources/mng-xxxx/checkstyle-test/pom.xml'
`../test/artifact/src/test/resources/mng-xxxx/checkstyle-test/src/main/java/Class.java' -> `./src/test/resources/mng-xxxx/checkstyle-test/src/main/java/Class.java'
`../test/artifact/src/test/resources/mng-xxxx/pom.xml' -> `./src/test/resources/mng-xxxx/pom.xml'
`../test/artifact/src/test/resources/mng-xxxx/readme.txt' -> `./src/test/resources/mng-xxxx/readme.txt'
|
Now add your test to the test suite by adding a new line to src\test\java\org\apache\maven\it\IntegrationTestSuite.java
| No Format |
|---|
suite.addTestSuite( MavenITmngXXXXDescriptionOfProblemTest.class );
|
Now run the suite:
| No Format |
|---|
brianf@sonoma /cygdrive/e/svn/Maven/maven-it-tests/core-it-suite
$ mvn |
| No Format |
>mvn test [INFO] Scanning for projects... [INFO] ---------------------------------------------------------------------------- [INFO] Building Maven Integration Tests [INFO] task-segment: [test] [INFO] ---------------------------------------------------------------------------- [INFO] [resources:resources] [INFO] Using default encoding to copy filtered resources. [INFO] [compiler:compile] [INFO] No sources to compileINFO] No sources to compile [INFO] [resources:testResources] [INFO] Using default encoding to copy filtered resources. [INFO] [compiler:testCompile] [INFO] Compiling 124 source files to e:\svn\Maven\maven-it-tests\core-it-suite\target\test-classes [INFO] [resourcessurefire:testResourcestest] [INFO] Using default encoding to copy filtered resources. [INFO] [compiler:testCompile] [INFO] Compiling 1 source file to E:\svn\Maven\maven-it-tests\test\artifact\target\test-classes [INFO] [surefire:test] [INFO] Surefire report directory: E:\svn\Maven\maven-it-tests\test\artifact\target\surefire-reports Surefire report directory: e:\svn\Maven\maven-it-tests\core-it-suite\target\surefire-reports Running integration tests for Maven 2.0.7 ------------------------------------------------------- T E S T S ------------------------------------------------------- T E S T S ------------------------------------------------------- Running mypackage.MavenITmngXXXXDescriptionOfProblemTest mngXXXXDescriptionOfProblem(testitMNGxxxx).. Ok Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 16.802 sec Results :-- Running org.apache.maven.it.IntegrationTestSuite Running integration tests for Maven 2.0.7 0000(testit0000).. Ok .... got get some coffee, it's gonna be a while .... MavenITmngXXXXDescriptionOfProblemTest...OK <-- our test...yeah! Tests run: 115, Failures: 22, Errors: 3, Skipped: 0, Time elapsed: 534.241 sec <<< FAILURE! Results : Failed tests: testit0002(org.apache.maven.it.MavenIT0002Test) Tests in error: testit0086(org.apache.maven.it.MavenIT0086Test) testit0087(org.apache.maven.it.MavenIT0087Test) testit0104(org.apache.maven.it.MavenIT0104Test) Tests run: 1115, Failures: 022, Errors: 03, Skipped: 0 [INFO] ------------------------------------------------------------------------ [INFOERROR] BUILD SUCCESSFULFAILURE [INFO] ------------------------------------------------------------------------ [INFO] Total time: 25 seconds [INFO] Finished at: Wed Aug 08 22:47:44 EDT 2007----- [INFO] Final Memory: 4M/10MThere are test failures. [INFO] ------------------------------------------------------------------------ |
Submitting your IT Test
Now that your IT is complete, create a zip, tgz or some other *normal* archive of your test and attach it to your Jira issue.
If you are a Maven committer, read the next section to see how to integrate your test into the core, or to apply someone else's test.
Integrating an IT into the core-integration-tests
First, check out the core-integration-tests
The sample project maps directly to the core-integration-tests structure. Assuming the test has been named uniquely, you can copy the contents of src/test directly over to core-integration-tests (don't copy from the root or you'll overwrite the pom).
| No Format |
|---|
/cygdrive/e/svn/Maven/maven-it-tests/core-integration-tests
$ cp ../test/artifact/src . -R -v
`../test/artifact/src/test/java/org/apache/maven/integrationtests/MavenITmngXXXXDescriptionOfProblemTest.java' -> `./src/test/java/org/apache/maven/integrationtests/MavenITmngXXXXDescriptionOfProblemTest.java'
`../test/artifact/src/test/resources/mng-xxxx-descriptionOfProblem/checkstyle-assembly/pom.xml' -> `./src/test/resources/mng-xxxx-descriptionOfProblem/checkstyle-assembly/pom.xml'
`../test/artifact/src/test/resources/mng-xxxx-descriptionOfProblem/checkstyle-assembly/src/main/resources/rule_set.xml' -> `./src/test/resources/mng-xxxx-descriptionOfProblem/checkstyle-assembly/src/main/resources/rule_set.xml'
`../test/artifact/src/test/resources/mng-xxxx-descriptionOfProblem/checkstyle-assembly/src/main/resources/stc_checks.xml' -> `./src/test/resources/mng-xxxx-descriptionOfProblem/checkstyle-assembly/src/main/resources/stc_checks.xml'
`../test/artifact/src/test/resources/mng-xxxx-descriptionOfProblem/checkstyle-assembly/target/classes/rule_set.xml' -> `./src/test/resources/mng-xxxx-descriptionOfProblem/checkstyle-assembly/target/classes/rule_set.xml'
`../test/artifact/src/test/resources/mng-xxxx-descriptionOfProblem/checkstyle-assembly/target/classes/stc_checks.xml' -> `./src/test/resources/mng-xxxx-descriptionOfProblem/checkstyle-assembly/target/classes/stc_checks.xml'
`../test/artifact/src/test/resources/mng-xxxx-descriptionOfProblem/checkstyle-test/pom.xml' -> `./src/test/resources/mng-xxxx-descriptionOfProblem/checkstyle-test/pom.xml'
`../test/artifact/src/test/resources/mng-xxxx-descriptionOfProblem/checkstyle-test/src/main/java/Class.java' -> `./src/test/resources/mng-xxxx-descriptionOfProblem/checkstyle-test/src/main/java/Class.java'
`../test/artifact/src/test/resources/mng-xxxx-descriptionOfProblem/pom.xml' -> `./src/test/resources/mng-xxxx-descriptionOfProblem/pom.xml'
`../test/artifact/src/test/resources/mng-xxxx-descriptionOfProblem/readme.txt' -> `./src/test/resources/mng-xxxx-descriptionOfProblem/readme.txt'
|
Now add your test to the testSuite by adding a new line to "src\test\java\org\apache\maven\integrationtests\IntegrationTestSuite.java"
| No Format |
|---|
suite.addTestSuite( MavenItmngXXXXDescriptionOfProblemTest.class );
|
Now run the suite:
[INFO] For more information, run Maven with the -e switch
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 9 minutes 12 seconds
[INFO] Finished at: Wed Aug 08 23:39:48 EDT 2007
[INFO] Final Memory: 4M/12M
[INFO] ------------------------------------------------------------------------
|
Don't panic if some tests fail. That's probably normal. Only Panic panic if your test doesn't fail and it was supposed to (especially if you didn't write it).
...