VFS Test Suite

Apache Commons VFS comes with a suite of (nearly 2000) tests (in core/src/test). The JUnit framework is used, and executed at build time via the Maven Surefire plugin by the mvn test goal. If 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.

The JUnit 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 dependency report):

Provider	Tested Against	External
ftp	Apache FtpServer	-Pftp -Dtest.ftp.uri=ftp://test:test@localhost:123
ftps	Apache FtpServer	-Pftps -Dtest.ftps.uri=ftps://test:test@localhost:123
hdfs	Apache Hadoop HDFS (MiniDFSCluster)	-P!no-test-hdfs (see below)
http	NHttpServer (local adaption of org.apache.http.examples.nio.NHttpServer)	-Phttp -Dtest.http.uri=http://localhost:123
https	(not tested)	N/A
jar	Local File Provider	N/A
local	Local File system	N/A
ram	In Memory test	N/A
res	Local File Provider / JAR Provider	N/A
sftp	Apache SSHD	-Psftp -Dtest.sftp.uri=sftp://testtest@localhost:123
tmp	Local File system	N/A
url	NHttpServer (local adaption of org.apache.http.examples.nio.NHttpServer) Local File system	-Phttp -Dtest.http.uri=http://localhost:128
webdav	Apache Jackrabbit Standalone Server	-Pwebdav -Dtest.webdav.uri=webdav://admin@localhost:123/repository/default
zip	Local File Provider	N/A
smb (sandbox)	(not tested)	-Psmb -Dtest.smb.uri=smb://DOMAIN\User:Pass@host/C$/commons-vfs2/core/target/test-classes/test-data

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 smb provider from the sandbox is not tested unless you specify a -Dtest.smb.uri and the -Psmb profile.

Running HDFS tests on Windows

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 (winutils.exe) and library (hadoop.dll) for the MiniCluster used in the test cases. Both files are not part of the Hadoop Commons 2.6.0 distribution (HADOOP-10051). After you built a compatible version, put them on your Windows PATH and then run the tests by disabling the no-test-hdfs profile, or by requesting explicitly the excluded tests:


> 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

Running SMB tests against Windows

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):


> 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

Note: there is a known test failure in this case, see VFS-562 on the JIRA bug tracker if you want to help.

Running tests with external servers

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).

Preparing external Servers

If you want to run the tests against external servers, run mvn install. 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 core/target/test-classes/test-data/.

Each repository/server should contain the following list of files for the tests to complete successfully.


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/

The Apache Commons Wiki contains a list of configuration examples for external servers. Please consider contributing if you have set up a specific scenario: https://wiki.apache.org/commons/VfsTestServers.