How to Add Automated Tests to LibreOffice Core

Contributing new automated test cases to the LibreOffice core repository ensures software stability, prevents regressions, and helps verify bug fixes. This guide provides a direct, step-by-step walkthrough on how to set up your environment, choose the appropriate test framework, implement CppUnit and UI tests, run them locally, and submit your changes through the LibreOffice Gerrit code review system.

1. Set Up the Development Environment

Before writing tests, ensure you have cloned the LibreOffice core repository and can build it successfully.

Clone the repository:

git clone https://gerrit.libreoffice.org/core libreoffice
cd libreoffice

Configure and build LibreOffice with tests enabled:
```
./autogen.sh --enable-dbgutil
make
```
Set up the Gerrit submission helper script:
```
./logerrit setup
```

2. Choose the Test Framework

LibreOffice uses different test frameworks depending on what you want to verify:

CppUnit Tests (C++): Best for non-GUI logic, file filters (DOCX, ODF, XLSX, etc.), core rendering, and module-specific internal logic.
UI Tests (Python / UITest): Best for interacting with dialogs, toolbars, menus, and verifying user interface behaviors.
Complex/Integration Tests (Java/Python): Used for broader integration checks across subsystems.

3. Writing a CppUnit Test (C++)

CppUnit tests are located inside the qa/unit/ directory of each respective module (e.g., sw/qa/core/, sc/qa/unit/, sd/qa/unit/).

Create or Modify a Test File

Navigate to the module directory. If you are adding a test case to an existing suite, open the relevant .cxx file (e.g., sw/qa/core/text/text.cxx) and add a new test function:

CPPUNIT_TEST_FIXTURE(SwCoreTest, testBugDescription)
{
    // Load a sample file from the test data folder
    createSwDoc("sample.docx");

    // Perform an operation or query the document model
    SwDoc* pDoc = getSwDoc();
    CPPUNIT_ASSERT(pDoc);

    // Verify expected behavior
    CPPUNIT_ASSERT_EQUAL(1, getPages());
}

Add Test Sample Files

If your test requires an input document, place it in the module’s test data directory (e.g., sw/qa/core/data/). Ensure the file is minimal and stripped of personal metadata.

Update the Makefile

If creating a completely new test suite file, register the new file in the corresponding CppunitTest_<module>_<name>.mk file located in the module root.

4. Writing a UI Test (Python)

UI tests are located inside <module>/qa/uitest/.

Create the Test Script

Create a new Python file or edit an existing one in the relevant module directory:

from uitest.framework import UITestCase
from uitest.uihelper.common import get_state_as_dict

class BugVerificationTest(UITestCase):
    def test_dialog_interaction(self):
        with self.ui_test.create_doc_in_start_center("writer"):
            # Open a dialog via UNO command
            self.xUITest.executeCommand(".uno:FontDialog")
            xDialog = self.xUITest.getTopFocusWindow()
            
            # Interact with UI elements
            xOkBtn = xDialog.getChild("ok")
            self.ui_test.close_dialog_through_button(xOkBtn)
            
            # Assert state
            self.assertEqual(1, len(self.ui_test.get_component().Text.String))

Register the UI Test

5. Run and Debug Tests Locally

Run your specific test directly using make to ensure it passes before submitting:

For CppUnit:
```
make CppunitTest_sw_core_test
```
For UITest:
```
make UITest_writer_tests
```

To run a single test function inside a CppUnit suite, use the CPPUNIT_TEST_NAME environment variable:

CPPUNIT_TEST_NAME="SwCoreTest::testBugDescription" make CppunitTest_sw_core_test

6. Submit Your Changes to Gerrit

Create a local branch and commit your test:

git checkout -b my-new-test
git add sw/qa/core/text/text.cxx
git commit -m "tdf#123456: Add automated test for Writer text wrap regression"

Note: If the test covers a Bugzilla issue, include the bug ID formatted as tdf#XXXXXX in the commit title.

Push the commit to Gerrit for code review:
```
./logerrit submitMaster
```
Monitor the Gerrit review URL provided in the terminal output. Automated continuous integration (Jenkins) bots will run your test across multiple operating systems, and reviewers will provide feedback.