Development/Calc Import Unit Tests

From The Document Foundation Wiki
Jump to: navigation, search

Introduction

There is a framework in Calc unit tests that allows to import given documents, and compare with a reference CSV file. It allows non-developers to write automatic regression tests for Calc import.

It would be amazing if some of the Calc users would write or extend the existing tests. Even if you could provide just one or two test cases you would help very much ensure that our next release will contain less bugs and that Calc becomes even more stable. Here are some examples that could be tested or the test extended:

  • normal content
  • the functions document should be extended to all build-in functions ( testing special cases, normal behavior, etc. )
  • advanced functions like sorted content, autofilter, subtotals, scenarios, etc.
  • some of the import bugs fixed during the 3.4 release cycle

Capabilities and Limitations

We can test the content of a calc document directly after loading it. It is quite easy to test the content of cells, that means the formula in a cell, the result as a value and the formatted result as a string. It is even possible to test the result of cells that are part of conditional formatting. It gets more complicated for other stuff since I don't have any csv handler for that or it might need some code to test it.

We can't test any dynamic changes in calc documents with this test ( there is ucalc for these cases). So for unit tests that try to emulate user input and/or changes that go beyond what is done during loading, can't be tested with this easy unit test.

Implementation

The tests are located in sc/qa/unit and consists of filters-test.cxx, subsequent_filters-test.cxx and the files in sc/qa/unit/data. Most tests are nowadays run at the subsequenttest target bun can easily be moved to the in-build test target. The splitting was necessary after these tests needed more than a minute and should therefore not be run during every incremental calc build. They should now only be run before pushing or some serious rework in some of the tested areas. They are also executed every time by one of our automatic build machines.

In the data directory there is one directory per supported file extensions (ods, xls, xlsx) and one directory contentCSV that only contains csv files. Please don't touch the other directories, they are for special tests) At the moment we have a for-named-ranges test, a database ranges test , a formatting test and a standard content test file. Additionally there is one file per directory for bugfix tests so that import bugs that are fixed once will not reoccur. If possible a new test case should be added to each of the three directories so that we test as much as possible for every filter.

Create new test

It's quite easy to write a new unit test:

  1. Create a document that should be tested or add/extend an existing sheet in a document.
  2. Create for every sheet a csv file that contains the expected result, formula or string that the test document should contain.
  3. Send it to the qa mailing list with a short statement that you licence the content under MPL/LGPLv3+.

Examples

The existing tests can be found in the source directory sc/qa/unit/data. You might either clone the whole git tree on your machine or download particular files from https://cgit.freedesktop.org/libreoffice/core/plain/sc/qa/unit/data, for example: