tobyweston / simple-excel

Generate excel sheets in Java

Simple-Excel

Simply modify and diff Excel sheets in Java

Simple-Excel wraps the Apache POI project with simple Java builders to modify sheets quickly and easily without all the boilerplate.

Use Hamcrest Matchers to compare workbooks and get fast feedback in tests. Comparing two sheets will compare the entire contents. You get a full report of the diff rather than just the first encountered difference.

Modifying an Excel sheet

Add styles, formula and content to cells programmatically via a simple DSL.

@Test
public void shouldReplaceCellsInComplicatedAlternateSyntaxExample() throws IOException {
public void shouldReplaceCellsInComplicatedAlternateSyntaxExample() throws IOException {
    HSSFWorkbook workbook = getWorkbook("shouldReplaceCellsInComplicatedExampleTemplate.xls");
    new PoiWorkbookMutator(workbook)
            .replaceCell(coordinate(C, 5), "Adding")
            .replaceCell(coordinate(D, 11), "a")
            .replaceCell(coordinate(G, 3), "cell")
            .replaceCell(coordinate(J, 10), "total")
            .replaceCell(coordinate(M, 15), 99.99d);

    assertThat(workbook, sameWorkbook(getWorkbook("shouldReplaceCellsInComplicatedExampleTemplateExpected.xls")));
}

A break in the matcher would show something like

java.lang.AssertionError:
Expected: equality of cell "G1"
     but: cell at "G1" contained <"Text"> expected <99.99D>
	at org.hamcrest.MatcherAssert.assertThat(MatcherAssert.java:20)

Adding Styling

Define some styles to reuse

private final Border border = border(top(NONE), right(THIN_SOLID), bottom(THIN_SOLID), left(THIN_SOLID));
private final DataFormat numberFormat = dataFormat("#,##0.00");

Next create your Cell with style information.

Cell cell = new DoubleCell(99.99d, aStyle().with(border).with(numberFormat));

and add it to a Row.

HashMap<ColumnIndex, Cell> columns = new HashMap<ColumnIndex, Cell>() {{
    put(column(A), cell);
}};
Row row = new Row(columns);

add your row to the workbook.

new PoiWorkbookMutator(workbook).mutator.appendRowToFirstSheet(row);

Using Matchers

To get more detailed output from mismatches, be sure to use MatcherAssert.assertThat from Hamcrest rather than the vanilla JUnit version (org.junit.Assert.assertThat). If you use the JUnit version, you'll get output similar to the following.

java.lang.AssertionError:
Expected: entire workbook to be equal
     got: <org.apache.poi.hssf.usermodel.HSSFWorkbook@6405ce40>

When, using MatcherAssert, you'd see something like this.

java.lang.AssertionError:
Expected: entire workbook to be equal
     but: cell at "C14" contained <"bananas"> expected <nothing>,
          cell at "C15" contained <"1,850,000 EUR"> expected <"1,850,000.00 EUR">,
          cell at "D16" contained <nothing> expected <"Tue Sep 04 06:30:00">
	at org.hamcrest.MatcherAssert.assertThat(MatcherAssert.java:20)

Caveats

• Currently, matching doesn't take into account styling. A cell is equal to another regardless of style. If one has a border for example, and the other doesn't but they have the same values, they are considered equal.

Download

Available for manual download via my Maven repository or add the repository to your 'pom.xml'.

<repositories>
    <repository>
        <id>bad.robot</id>
        <name>bad.robot repository on robotooling</name>
        <url>https://robotooling.com/maven/</url>
        <snapshots>
            <enabled>true</enabled>
            <updatePolicy>always</updatePolicy>
        </snapshots>
    </repository>
</repositories>

Then add a dependency.

<dependency>
    <groupId>bad.robot</groupId>
    <artifactId>simple-excel</artifactId>
    <version>1.2</version>
    <scope>compile</scope>
</dependency>

For more tools, see robotooling.com and visit my blog.

Releasing

Take a look at the release readme.

simple-excel's Issues

Just re-saving XLSX file without making changes causes cell count mismatch

Sorry for this support-type of question. I have saved an XLSX file as the expected result and the sameWorkbook() assertion passes whem comparing against a programmatically created workbook. However, if I just open and re-safe the XLSX file (without making any changes) with Excel on Windows, I get

java.lang.AssertionError: 
Expected: entire workbook to be equal
     but: got <2> cell(s) on row <1> expected <6> sheet "Summary",
          got <2> cell(s) on row <2> expected <6> sheet "Summary",
          got <2> cell(s) on row <5> expected <6> sheet "Summary",
          got <2> cell(s) on row <6> expected <6> sheet "Summary",
          got <2> cell(s) on row <7> expected <6> sheet "Summary",
          got <2> cell(s) on row <8> expected <6> sheet "Summary"

So somehow the number of (non-physical) cells seems to have changed. Any idea why, and how to deal with it? I wanted to update the XLSX file with new test expectations, but now I cannot due to the above issue which always make the test fail.

[Proposal] Ignore cells for testing

I use simple-excel to diff generated excels, this is a continuous process. It would be nice if there is a ignore on defined cells.

Example

java.lang.AssertionError: Comparing DemoExcelFile
Expected: entire workbook to be equal
     but: cell at "B4" contained <"2013-12-05 12:40:49.309"> expected <"2013-12-06 12:41:29.424">,
[..]

Cell comment ignored on comparison

Hi!

I found your library very useful. However another caveat I found was that comparison ignores cell comments. Would it be possible for you to add such feature?

Thanks for your effort as for today.

Best regards!

https://www.robotooling.com/ has invalid SSL certificate

I'd like to use the Maven repository via HTTPS to get rid of a Gradle warning, but using https://www.robotooling.com/maven/ as a repository breaks the build due to an invalid certificate. Interestingly, the certificate used seems to belong to GitHub! Would you mind fixing that by installing a proper certificate?

Links in sheets throw MalformedURLException

Internal links in Excel sheets aren't valid URLs and so throw a MalformedURLException when converted into HyperLinkCell types.

Support for apache poi 4

Hi, are there plans to support apache poi 4?
I'm not sure what changes that would entail

Why not on Maven Central?

Why is this library not published on Maven Central? It would be nice not to have to configure a special repository for it.

Missing bad.robot.excel.Cell Implementation

Not all Excel cell types have equivalents in Simple-Excel. Specifically looking for the percentage type.

Comparing rows with different number of cells containing value

I use WorkbookMatcher.sameWorkbook(Workbook) to compare a result workbook against an expected one.
In case the same sheet in both of the workbooks contain a row (at the same position) that has the same number of cells (last cell is the same) but the resulting row contains one physical cell (cell with value) that is not existing in expected row then comparing will not find this difference.

The reason is that CellNumberMatcher only checks whether the last cells in the two rows are the same, RowInSheetMatcher checks actual row against expected row calling CellsMatcher and CellsMatcher matches the physical cells of the expected row.

I advise checking the equality of the number of physical cells in the rows in CellNumberMatcher.

Comparing Excel with a difference (exclude a range from the Matcher)

Hi,

Is it possible to exclude some cells from the comparison?

attached is my code

MatcherAssert.assertThat(actual, WorkbookMatcher.sameWorkbook(expected));

Regards,

NOTICE file

Hi,

I'm very much interested in using simple-excel for testing with my company.

This is possible, as you kindly provide it under the Apache 2.0 license.

However, the license information in your code states there would be a NOTICE file with further information, and I cannot find such. Quote:
"See the NOTICE file distributed with this work for additional information."

Would you add a NOTICE file, so license information is not lost during distribution?
Apache provides a template:
https://www.apache.org/licenses/example-NOTICE.txt

Best regards & thank you for this great software

r

Publish to Central Maven Repo

Would be easier to adopt this library if it was published to http://search.maven.org/. Most IT orgs do not like artifacts to be pulled from a different central repo.

org.apache.poi.ss.usermodel.CellStyle are not reused

From reading the code, I think you end up generating a new CellStyle object every time a cell is added to the workbook. There is a limit of 64000 unique cell formats per workbook (https://support.office.com/en-nz/article/Excel-specifications-and-limits-16c69c74-3d6a-4aaf-ba35-e6eb276e8eaa).

I think if the CellStyles aren't being reused then it would be worth adding caching so that a Style object will only create a CellStyle on the workbook once. Then if you maintain a reference to a Style object then the same CellStyle instance from the workbook will be applied to each cell that uses the Style instance.

I'm happy to submit a pull request for this if you agree on my analysis.

Using it for reading excel files

Can we add code to this project so that it can read excel files and create new excel files for... let's say Names and Email ID's?