README.md
1<!--
2 Licensed to the Apache Software Foundation (ASF) under one
3 or more contributor license agreements. See the NOTICE file
4 distributed with this work for additional information
5 regarding copyright ownership. The ASF licenses this file
6 to you under the Apache License, Version 2.0 (the
7 "License"); you may not use this file except in compliance
8 with the License. You may obtain a copy of the License at
9
10 http://www.apache.org/licenses/LICENSE-2.0
11
12 Unless required by applicable law or agreed to in writing,
13 software distributed under the License is distributed on an
14 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 KIND, either express or implied. See the License for the
16 specific language governing permissions and limitations
17 under the License.
18-->
19
20# AOO test suite
21
22A pytest suite for an installed Apache OpenOffice 5 or later. It starts the office you point it at, drives it over UNO, and checks what comes out: ODF conformance in each save mode, import of ODF 1.2 and 1.3 files, document conversion, and a smoke test of the main components.
23
24The only required input is where the office is installed. The suite runs the same way on any platform and works with an install, so no source tree or build is needed.
25
26## What it checks
27
28| Directory | Needs an office | What |
29|---|---|---|
30| `tests/selftest` | no | The checkers (schema validation, package rules, document types, xml ids, formula syntax, decryption) against documents built to fail. |
31| `tests/harness` | no | Install discovery, the worker protocol and process handling, against fake installs and a fake worker. |
32| `tests/smoke` | yes | Start, connect, new/save/reload per application and save mode, conversion, and the old smoke test document (Writer, Calc, Impress, Draw, HTML, chart, Math, Bibliography, extensions). |
33| `tests/odf` | yes | Documents saved in each ODF save mode and checked against the ODF 1.2, 1.3 and 1.4 schemas and the package rules, with a second validator (odfvalidator) as a cross-check; documents the suite builds, saved and read back; saving twice for stable output; the error kinds of the extended modes compared with a stored baseline; password-protected documents decrypted by an independent implementation; about 300 OpenFormula cases evaluated in Calc; and, with a corpus, ODF 1.2 and 1.3 twins compared after import. Everything but the formula cases is marked `slow`. |
34
35## What it does not include
36
37Nothing third party and no binary documents are stored here.
38
39- Test documents come from the office under test: the templates and documents it ships, and documents it creates when the tests run. See [USAGE.md](USAGE.md#source-documents).
40- Some documents the suite can build are left out of the default run because converting them kills or stalls the office: Calc documents with tracked changes and all Base documents. They are listed with the reason in `data/built-excluded.tsv` and run with `python3 -m pytest -m crash`.
41- The OASIS schemas, jing and odfvalidator are downloaded once into a cache and checked against pinned sha256 values. Without them the tests that need them skip, with a reason.
42
43## Requirements
44
45- Python 3.10 or later and pytest 8 or later. Nothing else is needed to run the tests.
46- An installed AOO 5 or later.
47- A Python that can import `uno` from that install. The suite finds one itself, preferring the install's own `program/python`; see [USAGE.md](USAGE.md#pyuno).
48- Java, for the schema checks. Without it those items skip.
49
50## Quick start
51
52From this directory:
53
54 python3 -m pytest -m selftest # no office needed
55 PYTHONPATH=src python3 -m aootest.fetch # once: schemas and jing, about 20 MB
56 AOO_OFFICE=/path/to/install python3 -m pytest -m "not slow"
57 AOO_OFFICE=/path/to/install python3 -m pytest # everything, several minutes
58
59`AOO_OFFICE` can be an `.app` bundle, the install root, its `program` directory, or the `soffice` launcher.
60
61## Where it has been run
62
63macOS arm64 (an installed 5.1.0 and a trunk build) and Ubuntu 24.04 aarch64 (a trunk build). The Windows and FreeBSD code paths are covered by tests against fake installs only; nobody has run the suite on those systems yet.
64
65See [USAGE.md](USAGE.md) for options, expectation files and how to read results.
66