Introduction

In some cases you might be interested to know what changes were made on some file system.

The regular example is when you want to test whether an upgrade of your Application Under Test did not cause any unwanted changes on the file system.

 

Make sure there is no change on the file system

The following example makes a snapshot of some directory, then the real testing work (this could be a product upgrade for example) is done which might change this directory. Then another snapshot is made and both snapshots are compared.

All files and sub-directories of the pointed directory are checked and they must match - otherwise an error is thrown and the test fails

import com.axway.ats.action.filesystem.snapshot.FileSystemSnapshot;
...
// take first snapshot
FileSystemSnapshot snapshot1 = new FileSystemSnapshot( "snap1" );
snapshot1.addDirectory( "F1", "C:/dir1" );
snapshot1.takeSnapshot();

// DO SOME REAL WORK

// take second snapshot
FileSystemSnapshot snapshot2 = new FileSystemSnapshot( "snap2" );
snapshot2.addDirectory( "F1", "C:/dir1" );
snapshot2.takeSnapshot();

// check both snapshots are same
snapshot1.compare( snapshot2 );

As usual, when you want to take a snapshot on a remote host, there is constructor which takes an extra parameter which is the ATS Agent address

Monitoring more than one directory

You can freely add as many directories as needed by using the addDirectory method.

Snapshot alias

The snapshot name in the constructor is used when printing messages and errors, so try to provide a good name here

Directory alias

The first argument of the addDirectory method is a directory alias. This is mandatory parameter and is used to distinguish the directory pairs between both snapshots. This is case sensitive argument so make sure to keep the case for all method calls or better use a constant in the test code.

In some cases the name of monitored directories might change and that is why we need this alias name. For example you might be monitoring directory "C:/Programs/MyProductInstallDir_version1" from first snapshot and "C:/Programs/MyProductInstallDir_version5" from second snapshot - in this case the directory alias will tell us this is a pair of directories to check

 

Do not check some internal file or directory

Some of the snapshot content might not be of interest as it is expected to get changed

// take first snapshot
final String F1 = "dir1-alias";
FileSystemSnapshot snapshot1 = new FileSystemSnapshot( "snap1" );
snapshot1.addDirectory( F1, "C:/dir1" );
snapshot1.skipDirectory( F1, "sub-dir1/not_important_dir" );
snapshot1.skipDirectoryByRegex( F1, "sub-dir1/sub_[0-9]_[a-z]"); // skip directory by Regex (only the last directory token can be a Regex)
snapshot1.skipFile( F1, "sub-dir2/changing_file.xml" );
snapshot1.takeSnapshot();

// DO SOME REAL WORK

// take second snapshot
FileSystemSnapshot snapshot2 = new FileSystemSnapshot( "snap2" );
snapshot2.addDirectory( F1, "C:/dir1" );
snapshot2.takeSnapshot();

// check both snapshots are same without the entities that are to be skipped
snapshot1.compare( snapshot2 );

In this example we will not check not_important_dir and changing_file.xml. It does not matter if they are different between both snapshots, or they do not even exist - we will simply not deal with them.

Path to nested entities

When pointing to a nested file or directory, you provide the path to them starting from the path of the root directory (one added with addDirectory() method).
You also must specify which root directory they belong to by using the right directory alias.

 

Point some file of interest by using a regular expression

If for example want to skip more than one file, you can provide a regular expression instead of a static file name

snapshot1.skipFileByRegex( "F1", "sub-dir2/changing_file.*" );

In this case all files in the pointed sub-directory which name starts with changing_file will be skipped.

 

Skip just some file attributes of a file

There might be a case where you want to check a file is present, but you do not want to check its size and last modification time for example

snapshot1.skipFile( "F1", "sub-dir2/changing_file.xml", FileSystemSnapshot.SKIP_FILE_SIZE, FileSystemSnapshot.SKIP_FILE_MODIFICATION_TIME );

This way you can provide a list with the not important file attributes

Supported file attributes

The list of file attributes might grow in future.
All available values are available through constants starting with FileSystemSnapshot.SKIP_FILE_

 

Skip some file attributes of all files

You can configure globally some file attributes to be skipped or not by using the ActionLibraryConfigurator class

ActionLibraryConfigurator.getInstance().setFileSnapshotCheckModificationTime( false );

This way all modification times of all files are going to be ignored

Use the different ActionLibraryConfigurator.getInstance().getFileSnapshot* and ActionLibraryConfigurator.getInstance().setFileSnapshot* methods to see all the available options.

By default all checks are enabled.

 

Skip a file attribute globally, but still check it on a few files?

The following example gives two ways to achieve it:

// globally disable the modification time attribute
ActionLibraryConfigurator.getInstance().setFileSnapshotCheckModificationTime( false );

// first way - specify explicitly this attribute is important for this file
snapshot1.checkFile( "F1", "important_file.xml", FileSystemSnapshot.CHECK_FILE_MODIFICATION_TIME );

// second way - specify all supported attributes are important for this file
snapshot1.checkFile( "F1", "important_file.xml" );

 

Keep the snapshot into a file

You can persist the snapshot into an XML file and retrieve it when needed.

FileSystemSnapshot snapshot1 = new FileSystemSnapshot( "snap1" );
snapshot1.addDirectory( "F1", "C:/dir1" );
snapshot1.takeSnapshot();
snapshot1.toLocalFile( "C:/snapshot_file_for_product_version1.xml" );

The above code makes a snapshot of the file system and saves it into a file. Imagine a new product version came to test, now you can make sure the file system is same as with the previous version.

// load the old snapshot info from the backup file
FileSystemSnapshot oldSnapshot = FileSystemSnapshot.fromLocalFile( "product version 1", "C:/snapshot_file_for_product_version1.xml");

// make a new snapshot which reflects the current product version
FileSystemSnapshot newSnapshot = new FileSystemSnapshot( "product version 2" );
newSnapshot.addDirectory( "F1", "C:/dir1" );
newSnapshot.takeSnapshot();

// compare both snapshots
newSnapshot.compare( oldSnapshot );

Local and Remote files

toLocalFile and fromLocalFile methods work on the local host

In similar way you can use toRemoteFile and fromRemoteFile methods from remote host

 

Make two identical snapshots without duplicating the code

In real life you may need to use lots of methods in order to describe properly all the files and directories that are to be checked and this will lead to longer code than the presented in this guide.
If you need to have 2 snapshots with same internal structure, but only taken at a different time, you will need to duplicate a lot of code.

Instead of repeating the same long code for the second snapshot, you can use a handy method:

// create the initial snapshot
FileSystemSnapshot snapshot1 = new FileSystemSnapshot( "snap1" );
snapshot1.addDirectory( "F1", "C:/dir1" );
snapshot1.addDirectory( "F2", "C:/dir2" );
snapshot1.addDirectory( "F3", "C:/dir3" );
snapshot1.skipDirectory( "F1", "sub-dir1/not_important_dir" );
snapshot1.skipDirectory( "F1", "sub-dir2/not_important_dir" );
snapshot1.skipDirectory( "F1", "sub-dir1/another_not_important_dir" );
snapshot1.skipFile( "F1", "sub-dir2/changing_file.xml" );
snapshot1.skipFile( "F1", "sub-dir1/.*xml" );
snapshot1.takeSnapshot();

// create the second snapshot
FileSystemSnapshot snapshot2 = snapshot1.newSnapshot( "snap2" );
snapshot2.takeSnapshot();

// now compare them
snapshot1.compare( snapshot2); 


Compare some files' content instead of their file attributes

Imagine you have some human readable configuration file. The file got changed in a way that a line is moved a little down or a new white space character appeared. We tell you it is a different file(as long as it size and MD5 checksum do not match), but you tell us the files have same content indeed.

Here is how to deal with such files. Currently this includes XML, Properties, INI and plain TEXT files.


Make your own report about the found differences

If you do not like the way we present the found differences, you can make your own:

import com.axway.ats.common.filesystem.snapshot.FileSystemSnapshotException;
import com.axway.ats.common.filesystem.snapshot.equality.EqualityState;
import com.axway.ats.common.filesystem.snapshot.equality.FileTrace;

// make both snapshots as described in the previous sections of this page

try {
    // compare both snapshots
    snapshot2.compare( snapshot1 );
} catch ( FileSystemSnapshotException e ) {
    // if not expected differences are found, you will get this exception
    // you catch it here so can extract the differences out of the exception
    FileSystemEqualityState equalityState = e.getEqualityState();

    // now use the available method to get the list of differences and construct your own report style
    List<FileTrace> differentFiles = equalityState.getDifferentFiles();
    List<FileTrace> filesInOneSnapshotOnly = equalityState.getFilesPresentInOneSnapshotOnly( "snap1" );
    List<FileTrace> directoriesInOneSnapshotOnly= equalityState.getDirectoriesPresentInOneSnapshotOnly( "snap1" );

    // inspect FileTrace getter methods to extract the needed info
}

 

Back to parent page

Go to Table of Contents