Report Utilities library

This is a Java library with some utilities to check if two files are equal or different. It could be useful to verify that a file generated by a given code, is compliant with a golden copy.

Getting Started

To get you started you can simply clone the java-report-test-utilities repository and install the dependencies.

Prerequisites

You need git to clone the java-report-test-utilities repository.

You will need Java™ SE Development Kit 8 and Maven.

Clone

Clone the java-report-test-utilities repository using git:

git clone https://github.com/systelab/java-report-test-utilities.git
cd java-report-test-utilities

Install Dependencies

In order to install the dependencies, you must run:

mvn clean install

Release

In order to release a new version:

Step 1. Update the version in your pom.xml file. For example:

<version>v.1.3.1</version>

Step 2. Commit and push in the master branch, and generate a new Release by pressing the button "Draft new release".

In the example use v.1.3.1 as the Tag version, and 1.3.1 as the release title.

Step 3. Head to https://jitpack.io and look up "systelab/java-report-test-utilities". Choose the new version and press the button "Get it". Check the log to verify that everything is fine.

Using the library

In order to use the library, you should add the dependency to your project.

Dependency

Gradle

In order to use the library, you should:

Add it in your root build.gradle at the end of repositories:

allprojects {
    repositories {
        ...
        maven { url 'https://jitpack.io' }
    }
}

Step 2. Add the dependency

dependencies {
    implementation 'com.github.systelab:java-report-test-utilities:v1.3.1'
}

Maven

Step 1. Add the JitPack repository to your build file

	<repositories>
		<repository>
		    <id>jitpack.io</id>
		    <url>https://jitpack.io</url>
		</repository>
	</repositories>

Step 2. Add the dependency

	<dependency>
	    <groupId>com.github.systelab</groupId>
	    <artifactId>java-report-test-utilities</artifactId>
	    <version>v1.3.1</version>
	</dependency>

Code

Use PDFComparator and ExcelComparator compareFiles method as needed.

public static ComparisonResult compareFiles(File expectedFile, File actualFile)

The compareFiles method, currently only for Excel, has an additional argument of ExcelComparisonSettings type.

public static ComparisonResult compareFiles(File expectedFile, File actualFile, ExcelComparisonSettings excelComparisonSettings)

It allows users to customize how two Excel files are compared: Two attributes are available: compareCellStyle and excelCellExclusions.

compareCellStyle: This is a boolean attribute. When set to true, the comparison process will also examine the style of cells. For instance, even if two cells in different files have identical content, they would be flagged as different if their styles vary—such as one having a green background while the other has a red one.

boolean compareCellStyle = true;
ExcelComparisonSettings excelComparisonSettings = new ExcelComparisonSettings(compareCellStyle);
ExcelComparator.compareFiles(expectedFile, actualFile, excelComparisonSettings);

excelCellExclusions: This is a list specifying which cells should be excluded from the comparison. It's particularly helpful in cases where certain cells, like those with timestamps, shouldn't be compared. For instance, to exclude the cell in column 1 (index 0) of row 6 (index 5) on sheet 1 (index 0), you would pass the indices to the constructor in the order: sheet, row, cell. Note that indices start at 0, not 1.

List<ExcelCellExclusion> excelCellExclusions = new ArrayList<>();
excelCellExclusions.add(new ExcelCellExclusion(0, 5, 0));
ExcelComparisonSettings excelComparisonSettings = new ExcelComparisonSettings(excelCellExclusions);
ExcelComparator.compareFiles(expectedFile, actualFile, excelComparisonSettings);

In a Unit Test, to assert that files are equal or different, it is suggested to use the assertEquals and assertNotEquals static methods in the ComparisonResultAssertions utility class.

For example:

    @Test
    public void compareFilesEqual() throws IOException {
        File file = new File(RESOURCE_PATH + "file1.pdf");
        ComparisonResultAssertions.assertEquals(compareFiles(file, file));
    }


    @Test
    public void compareFilesNotEqual() throws IOException {
        File expectedFile = new File(RESOURCE_PATH + "file1.pdf");
        File actualFile = new File(RESOURCE_PATH + "file2.pdf");
        ComparisonResultAssertions.assertNotEquals(compareFiles(expectedFile, actualFile));
    }