DocFormats includes a test suite which exercises most (ideally all) functions of the library. The test strategy is based on having one file per test, consisting of a action, input, and output.

 

The action is a task to be performed with the library. It does not necessarily correspond to a specific function, but rather a way of using the library's API to do something. The most common types of tests are "get", "update", and "create".

 

- The get tests take a .docx file as input and produce HTML as output.

- The update tests take a .docx file and an updated HTML file as input, and produce an updated .docx file as output

- The create tests take a HTML file as input, and produce a .docx file as output

 

# Running the tests

 

The dfutil program contains the logic necessary to run the test harness. Assuming DOCFORMATS_DIR is set to the repository root, run it like this:

 

    dfutil -test $DOCFORMATS_DIR/tests

 

This will recursively scan through the specified directory looking for all files with the extension .test, and execute them (see below for details of the format). The first line of each .test file specifies the action to be tested.

 

If you find a test that is failing, you can run just that one particular test, e.g. as follows:

 

    dfutil -test $DOCFORMATS_DIR/tests/tables/word/update-vsplit06.test

 

This will print the actual result to standard output, which you can visually compare with the expected result inside the .test file itself.

 

To see the difference between the actual and expected results, you can then run the following command:

 

    dfutil -testdiff $DOCFORMATS_DIR/tests/tables/word/update-vsplit06.test

 

This executes the `diff` command on the actual and expected output, and writes the output of `diff` to standard output.

 

# Test format

 

All of the tests are UTF-8 encoded text files, in what we refer to as a "test package" format. A test package action name followed by one or more *parts*, each of which is UTF-8 encoded text (and can possibly be a nested test package). Each part has a name.

 

For file formats such as .docx which are usually stored as zip files containing XML data, a test package contains the uncompressed contents, with each XML file being a separate part. For example, in many of the .docx test cases, there is one item for document.xml, another for styles.xml, and in some cases numbering.xml. The functions in Plain.c interpret these and convert them into DocFormats' internal package data structure.

 

Here is a simple example of a test package:

 

    #item one.txt

    This is a text file

    #item two.txt

    And here's another

 

Here is an example of a nested test package, that might be used for a function that converts all input files to uppercase:

 

    #item input

    ##item one.txt

    This is a text file

    ##item two.txt

    And here's another

    #item expected

    ##item one.txt

    THIS IS A TEXT FILE

    ##item two.txt

    AND HERE'S ANOTHER

 

In addition to this, the first line of a .test file must have the name of the action to be performed.

 

 

  • No labels