src/site/xdoc/testing.xml - commons-vfs - Git at Google

 <!--
     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.
 -->
 <document>
     <properties>
         <title>Testing</title>
         <author email="dev@commons.apache.org">Apache Commons Developers</author>
     </properties>

     <body>
         <section name="VFS Test Suite">
             <p>
               Apache Commons VFS comes with a suite of (nearly 2000) tests (in <code>core/src/test</code>). The JUnit framework
               is used, and executed at build time via the Maven
               <a href="http://maven.apache.org/surefire/maven-surefire-plugin/">Surefire plugin</a> by the <code>mvn test</code> goal.
               It you plan to contribute a patch for a bug or feature, make sure to also provide a test
               which can reproduce the bug or exercise the new feature. Also run the whole test suite against the patched code.
             </p>
             <p>
               The <a href="http://junit.org">JUnit</a> tests will execute unit, compile but also integration tests to test the API and the implementation.
               The local file provider is tested in a directory of the local file system. Virtual providers (compression and archive)
               and resource access is based on this test directory as well. For testing the other providers some test servers are started.
               The following table described the details (for versions have a look in the
               <a href="commons-vfs2/dependencies.html#test">dependency report</a>):
             </p>
 <table><tr><th>Provider</th><th>Tested Against</th><th>External</th></tr>
 <tr><td>ftp</td><td><a href="http://mina.apache.org/ftpserver-project/">Apache FtpServer</a></td><td>-Pftp -Dtest.ftp.uri=ftp://test:test@localhost:123</td></tr>
 <tr><td>ftps</td><td><a href="http://mina.apache.org/ftpserver-project/">Apache FtpServer</a></td><td>-Pftps -Dtest.ftps.uri=ftps://test:test@localhost:123</td></tr>
 <tr><td>hdfs</td><td>Apache Hadoop HDFS (<a href="https://wiki.apache.org/hadoop/HowToDevelopUnitTests">MiniDFSCluster</a>)</td><td>-P!no-test-hdfs (see below)</td></tr>
 <tr><td>http</td><td>NHttpServer (local adaption of org.apache.http.examples.nio.NHttpServer)</td><td>-Phttp -Dtest.http.uri=http://localhost:123</td></tr>
 <tr><td>https</td><td>(not tested)</td><td>N/A</td></tr>
 <tr><td>jar</td><td>Local File Provider</td><td>N/A</td></tr>
 <tr><td>local</td><td>Local File system</td><td>N/A</td></tr>
 <tr><td>ram</td><td>In Memory test</td><td>N/A</td></tr>
 <tr><td>res</td><td>Local File Provider / JAR Provider</td><td>N/A</td></tr>
 <tr><td>sftp</td><td><a href="http://mina.apache.org/sshd-project/index.html">Apache SSHD</a></td><td>-Psftp -Dtest.sftp.uri=sftp://testtest@localhost:123</td></tr>
 <tr><td>tmp</td><td>Local File system</td><td>N/A</td></tr>
 <tr><td>url</td><td>NHttpServer (local adaption of org.apache.http.examples.nio.NHttpServer)<br/>Local File system</td><td>-Phttp -Dtest.http.uri=http://localhost:128</td></tr>
 <tr><td>webdav</td><td><a href="http://jackrabbit.apache.org/standalone-server.html">Apache Jackrabbit Standalone Server</a></td><td>-Pwebdav -Dtest.webdav.uri=webdav://admin@localhost:123/repository/default</td></tr>
 <!-- <tr><td>webdavs</td><td>Apache Jackrabbit Standalone</td><td>-Pwebdav -Dtest.webdav.uri=webdav://admin@localhost:123/repository/default</td></tr> -->
 <tr><td>zip</td><td>Local File Provider</td><td>N/A</td></tr>
 <tr><td>smb (sandbox)</td><td>(not tested)</td><td>-Psmb -Dtest.smb.uri=smb://DOMAIN\User:Pass@host/C$/commons-vfs2/core/target/test-classes/test-data</td></tr>
 </table>
             <p>
               Some tests are operating-system specific. Some Windows File Name tests are only run on Windows
               and the HDFS test is skipped in case of Windows (because it requires additional binaries). It is therefore
               a good idea to run the tests at least on Windows and Linux/Unix before release. The <code>smb</code> provider
               from the sandbox is not tested unless you specify a <code>-Dtest.smb.uri</code> and the <code>-Psmb</code> profile.
             </p>
         </section>
         <section name="Running HDFS tests on Windows">
             <p>
               The HDFS integration tests use the HDFS MiniCluster. This does not work on Windows without special preparation:
               you need to build and provide the (2.6.0) native binary (<code>winutils.exe</code>) and library (<code>hadoop.dll</code>) for the
               MiniCluster used in the test cases. Both files are not part of the Hadoop Commons 2.6.0
               distribution (<a href="https://issues.apache.org/jira/browse/HADOOP-10051">HADOOP-10051</a>). After you built
               a compatible version, put them on your Windows <code>PATH</code> and then run the tests
               by disabling the <code>no-test-hdfs</code> profile, or by requesting explicitly the excluded tests:
             </p>
             <source><![CDATA[
 > set VFS=C:\commons-vfs2-project\core
 > cd %VFS%\core
 > mkdir bin\
 > copy \temp\winutils.exe \temp\hadoop.dll bin\
 > set HADOOP_HOME=%VFS%\core
 > set PATH=%VFS%\core\bin;%PATH%
 > winutils.exe systeminfo
 8518668288,8520572928,4102033408,4544245760,8,1600000,6042074
 > mvn -P!no-test-hdfs clean test     # runs all test and HDFS tests
 > mvn clean test -Dtest=org.apache.commons.vfs2.provider.hdfs.test.HdfsFileProviderTest,org.apache.commons.vfs2.provider.hdfs.test.HdfsFileProviderTestCase
 ...
 Tests run: 13, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 13.006 sec - in org.apache.commons.vfs2.provider.hdfs.test.HdfsFileProviderTest
 Tests run: 77, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 11.728 sec - in org.apache.commons.vfs2.provider.hdfs.test.HdfsFileProviderTestCase]]></source>
         </section>

         <section name="Running SMB tests against Windows">
             <p>
               The SMB provider from the sandbox project cannot be tested automatically. You need to prepare a CIFS/SMB server
               to test it manually. If you develop on Windows, the following procedure uses the Windows File Sharing and does
               not require to prepare the data directory (as you can directly point to your workspace):
             </p>
             <source><![CDATA[
 > set VFS=C:\commons-vfs2-project
 > cd %VFS%
 > mvn clean install -Pinclude-sandbox -DskipTests  # prepares test data and parent
 > cd %VFS%\sandbox
 > mvn test -Psmb -Dtest.smb.url=smb//Domain\User:Pass@yourhost/C$/commons-vfs2-project/core/target/test-classes/test-data
 ...
 Tests run: 82, Failures: 0, Errors: 1, Skipped: 0]]></source>
             <p>
               Note: there is a known test failure in this case, see
               <a href="https://issues.apache.org/jira/browse/VFS-562">VFS-562</a> on the JIRA bug tracker if you want
               to help.
             </p>
         </section>

         <section name="Running tests with external servers">
             <p>
               In order to test VFS for compatibility with other implementations (or in case of SMB to
               test it manually) some of the integration tests can be configured to connect to custom URL.
               This generally involves preparing the server, selecting a profile and specifying the URL in
               a system property (see table above).
             </p>

             <subsection name="Preparing external Servers">
                 <p>
                   If you want to run the tests against external servers, run <code>mvn install</code>.
                   This will compile all the source and test source and then run all the tests
                   for providers that use the local file system.
                   After running the maven build, the test data can be found in
                   <code>core/target/test-classes/test-data/</code>.
                 </p>
                 <p>
                   Each repository/server should contain the following list of files for the tests to
                   complete successfully.
                 </p>
                 <source><![CDATA[
 code/sealed/AnotherClass.class
 code/ClassToLoad.class
 largefile.tar.gz
 nested.jar
 nested.tar
 nested.tbz2
 nested.tgz
 nested.zip
 read-tests/dir1/file1.txt
 read-tests/dir1/file2.txt
 read-tests/dir1/file3.txt
 read-tests/dir1/subdir1/file1.txt
 read-tests/dir1/subdir1/file2.txt
 read-tests/dir1/subdir1/file3.txt
 read-tests/dir1/subdir2/file1.txt
 read-tests/dir1/subdir2/file2.txt
 read-tests/dir1/subdir2/file3.txt
 read-tests/dir1/subdir3/file1.txt
 read-tests/dir1/subdir3/file2.txt
 read-tests/dir1/subdir3/file3.txt
 read-tests/empty.txt
 read-tests/file1.txt
 read-tests/file space.txt
 read-tests/file%.txt
 test-hash-#test.txt
 test.jar
 test.mf
 test.policy
 test.tar
 test.tbz2
 test.tgz
 test.zip
 write-tests/]]></source>
                 <p>
                   The Apache Commons Wiki contains a list of configuration examples for external servers.
                   Please consider contributing if you have set up a specific scenario:
                   <a href="https://wiki.apache.org/commons/VfsTestServers">https://wiki.apache.org/commons/VfsTestServers</a>.
                 </p>
             </subsection>
         </section>
     </body>
 </document>
	<!--
	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.
	-->
	<document>
	<properties>
	<title>Testing</title>
	<author email="dev@commons.apache.org">Apache Commons Developers</author>
	</properties>

	<body>
	<section name="VFS Test Suite">
	<p>
	Apache Commons VFS comes with a suite of (nearly 2000) tests (in <code>core/src/test</code>). The JUnit framework
	is used, and executed at build time via the Maven
	<a href="http://maven.apache.org/surefire/maven-surefire-plugin/">Surefire plugin</a> by the <code>mvn test</code> goal.
	It you plan to contribute a patch for a bug or feature, make sure to also provide a test
	which can reproduce the bug or exercise the new feature. Also run the whole test suite against the patched code.
	</p>
	<p>
	The <a href="http://junit.org">JUnit</a> tests will execute unit, compile but also integration tests to test the API and the implementation.
	The local file provider is tested in a directory of the local file system. Virtual providers (compression and archive)
	and resource access is based on this test directory as well. For testing the other providers some test servers are started.
	The following table described the details (for versions have a look in the
	<a href="commons-vfs2/dependencies.html#test">dependency report</a>):
	</p>
	<table><tr><th>Provider</th><th>Tested Against</th><th>External</th></tr>
	<tr><td>ftp</td><td><a href="http://mina.apache.org/ftpserver-project/">Apache FtpServer</a></td><td>-Pftp -Dtest.ftp.uri=ftp://test:test@localhost:123</td></tr>
	<tr><td>ftps</td><td><a href="http://mina.apache.org/ftpserver-project/">Apache FtpServer</a></td><td>-Pftps -Dtest.ftps.uri=ftps://test:test@localhost:123</td></tr>
	<tr><td>hdfs</td><td>Apache Hadoop HDFS (<a href="https://wiki.apache.org/hadoop/HowToDevelopUnitTests">MiniDFSCluster</a>)</td><td>-P!no-test-hdfs (see below)</td></tr>
	<tr><td>http</td><td>NHttpServer (local adaption of org.apache.http.examples.nio.NHttpServer)</td><td>-Phttp -Dtest.http.uri=http://localhost:123</td></tr>
	<tr><td>https</td><td>(not tested)</td><td>N/A</td></tr>
	<tr><td>jar</td><td>Local File Provider</td><td>N/A</td></tr>
	<tr><td>local</td><td>Local File system</td><td>N/A</td></tr>
	<tr><td>ram</td><td>In Memory test</td><td>N/A</td></tr>
	<tr><td>res</td><td>Local File Provider / JAR Provider</td><td>N/A</td></tr>
	<tr><td>sftp</td><td><a href="http://mina.apache.org/sshd-project/index.html">Apache SSHD</a></td><td>-Psftp -Dtest.sftp.uri=sftp://testtest@localhost:123</td></tr>
	<tr><td>tmp</td><td>Local File system</td><td>N/A</td></tr>
	<tr><td>url</td><td>NHttpServer (local adaption of org.apache.http.examples.nio.NHttpServer)<br/>Local File system</td><td>-Phttp -Dtest.http.uri=http://localhost:128</td></tr>
	<tr><td>webdav</td><td><a href="http://jackrabbit.apache.org/standalone-server.html">Apache Jackrabbit Standalone Server</a></td><td>-Pwebdav -Dtest.webdav.uri=webdav://admin@localhost:123/repository/default</td></tr>
	<!-- <tr><td>webdavs</td><td>Apache Jackrabbit Standalone</td><td>-Pwebdav -Dtest.webdav.uri=webdav://admin@localhost:123/repository/default</td></tr> -->
	<tr><td>zip</td><td>Local File Provider</td><td>N/A</td></tr>
	<tr><td>smb (sandbox)</td><td>(not tested)</td><td>-Psmb -Dtest.smb.uri=smb://DOMAIN\User:Pass@host/C$/commons-vfs2/core/target/test-classes/test-data</td></tr>
	</table>
	<p>
	Some tests are operating-system specific. Some Windows File Name tests are only run on Windows
	and the HDFS test is skipped in case of Windows (because it requires additional binaries). It is therefore
	a good idea to run the tests at least on Windows and Linux/Unix before release. The <code>smb</code> provider
	from the sandbox is not tested unless you specify a <code>-Dtest.smb.uri</code> and the <code>-Psmb</code> profile.
	</p>
	</section>
	<section name="Running HDFS tests on Windows">
	<p>
	The HDFS integration tests use the HDFS MiniCluster. This does not work on Windows without special preparation:
	you need to build and provide the (2.6.0) native binary (<code>winutils.exe</code>) and library (<code>hadoop.dll</code>) for the
	MiniCluster used in the test cases. Both files are not part of the Hadoop Commons 2.6.0
	distribution (<a href="https://issues.apache.org/jira/browse/HADOOP-10051">HADOOP-10051</a>). After you built
	a compatible version, put them on your Windows <code>PATH</code> and then run the tests
	by disabling the <code>no-test-hdfs</code> profile, or by requesting explicitly the excluded tests:
	</p>
	<source><![CDATA[
	> set VFS=C:\commons-vfs2-project\core
	> cd %VFS%\core
	> mkdir bin\
	> copy \temp\winutils.exe \temp\hadoop.dll bin\
	> set HADOOP_HOME=%VFS%\core
	> set PATH=%VFS%\core\bin;%PATH%
	> winutils.exe systeminfo
	8518668288,8520572928,4102033408,4544245760,8,1600000,6042074
	> mvn -P!no-test-hdfs clean test # runs all test and HDFS tests
	> mvn clean test -Dtest=org.apache.commons.vfs2.provider.hdfs.test.HdfsFileProviderTest,org.apache.commons.vfs2.provider.hdfs.test.HdfsFileProviderTestCase
	...
	Tests run: 13, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 13.006 sec - in org.apache.commons.vfs2.provider.hdfs.test.HdfsFileProviderTest
	Tests run: 77, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 11.728 sec - in org.apache.commons.vfs2.provider.hdfs.test.HdfsFileProviderTestCase]]></source>
	</section>

	<section name="Running SMB tests against Windows">
	<p>
	The SMB provider from the sandbox project cannot be tested automatically. You need to prepare a CIFS/SMB server
	to test it manually. If you develop on Windows, the following procedure uses the Windows File Sharing and does
	not require to prepare the data directory (as you can directly point to your workspace):
	</p>
	<source><![CDATA[
	> set VFS=C:\commons-vfs2-project
	> cd %VFS%
	> mvn clean install -Pinclude-sandbox -DskipTests # prepares test data and parent
	> cd %VFS%\sandbox
	> mvn test -Psmb -Dtest.smb.url=smb//Domain\User:Pass@yourhost/C$/commons-vfs2-project/core/target/test-classes/test-data
	...
	Tests run: 82, Failures: 0, Errors: 1, Skipped: 0]]></source>
	<p>
	Note: there is a known test failure in this case, see
	<a href="https://issues.apache.org/jira/browse/VFS-562">VFS-562</a> on the JIRA bug tracker if you want
	to help.
	</p>
	</section>

	<section name="Running tests with external servers">
	<p>
	In order to test VFS for compatibility with other implementations (or in case of SMB to
	test it manually) some of the integration tests can be configured to connect to custom URL.
	This generally involves preparing the server, selecting a profile and specifying the URL in
	a system property (see table above).
	</p>

	<subsection name="Preparing external Servers">
	<p>
	If you want to run the tests against external servers, run <code>mvn install</code>.
	This will compile all the source and test source and then run all the tests
	for providers that use the local file system.
	After running the maven build, the test data can be found in
	<code>core/target/test-classes/test-data/</code>.
	</p>
	<p>
	Each repository/server should contain the following list of files for the tests to
	complete successfully.
	</p>
	<source><![CDATA[
	code/sealed/AnotherClass.class
	code/ClassToLoad.class
	largefile.tar.gz
	nested.jar
	nested.tar
	nested.tbz2
	nested.tgz
	nested.zip
	read-tests/dir1/file1.txt
	read-tests/dir1/file2.txt
	read-tests/dir1/file3.txt
	read-tests/dir1/subdir1/file1.txt
	read-tests/dir1/subdir1/file2.txt
	read-tests/dir1/subdir1/file3.txt
	read-tests/dir1/subdir2/file1.txt
	read-tests/dir1/subdir2/file2.txt
	read-tests/dir1/subdir2/file3.txt
	read-tests/dir1/subdir3/file1.txt
	read-tests/dir1/subdir3/file2.txt
	read-tests/dir1/subdir3/file3.txt
	read-tests/empty.txt
	read-tests/file1.txt
	read-tests/file space.txt
	read-tests/file%.txt
	test-hash-#test.txt
	test.jar
	test.mf
	test.policy
	test.tar
	test.tbz2
	test.tgz
	test.zip
	write-tests/]]></source>
	<p>
	The Apache Commons Wiki contains a list of configuration examples for external servers.
	Please consider contributing if you have set up a specific scenario:
	<a href="https://wiki.apache.org/commons/VfsTestServers">https://wiki.apache.org/commons/VfsTestServers</a>.
	</p>
	</subsection>
	</section>
	</body>
	</document>