sw/qa/extras/README

   1 = How to add a new Writer filter test
   2
   3 The `sw/qa/extras/` subdirectory has multiple import and export filter unit
   4 tests. This file documents how to add new testcases to this framework.
   5
   6 == Import tests
   7
   8 Import tests are the easier ones. First you need to use
   9 `CPPUNIT_TEST_FIXTURE()` and `load()`, so the framework will load the
  10 specified file to `mxComponent`, which represents the UNO model of the
  11 document.
  12
  13 The rest of the testcase is about implementing the test method asserting this
  14 document model: use the UNO API to retrieve properties, then use
  15 `CPPUNIT_ASSERT_EQUAL()` to test against an expected value.
  16
  17 See below for more details on writing the UNO code see below.
  18
  19 === Direct XPath assertions on the layout dump
  20
  21 In most cases you want to assert the document model, but sometimes asserting
  22 the layout is easier. If you want to do so, check the methods in
  23 test/source/xmltesttools.cxx. If you want
  24 to have a look at the XML document that can be asserted, start soffice with the
  25 `SW_DEBUG=1` environment variable, load a document, press F12, and have a look
  26 at the `layout.xml` file in the current directory. Once you find the needed
  27 information in that file, you can write your XPath expression to turn that into
  28 a testcase.
  29
  30 (Similarly, Shift-F12 produces a `nodes.xml` for the document model dump, but
  31 it's unlikely that you'll need that in a unit test.)
  32
  33 == Export tests
  34
  35 Export tests are similar. Given that test documents are easier to provide in
  36 some format (instead of writing code to build the documents from scratch) in
  37 most cases, we will do an import, then do an export (to invoke the code we want
  38 to test) and then do an import again, so we can do the testing by asserting the
  39 document model, just like we did for import tests.
  40
  41 Yes, this means that you can only test the export code (using this framework)
  42 if the importer is working correctly. (But that's not so bad, users usually
  43 expect a feature to work in both the importer and the exporter.)
  44
  45 The only difference is that in these tests the test method is called twice:
  46 once after the initial import -- so you can see if the export fails due to an
  47 import problem in fact -- and once after the export and import.
  48
  49 === Direct XPath assertions
  50
  51 Another alternative is to assert the resulted export document directly.
  52 Currently this is only implemented for DOCX, which is a zipped XML, so it's
  53 possible to evaluate XPath checks. A check looks like this:
  54
  55 xmlDocPtr pXmlDoc = parseExport("word/document.xml");
  56 assertXPath(pXmlDoc, <xpath selecting the node>, <attribute>, <value>);
  57
  58 It's important to check for the NULL pointer here, it's expected that it'll be
  59 NULL when the test runs first (after the first import), as there is nothing
  60 exported yet. For other XPath assert variants, see the `XmlTestTools` class.
  61
  62 == Helper methods
  63
  64 When two or more tests do the same (for example determine the number of
  65 characters in the document), helper methods are introduced to avoid code
  66 duplication. When you need something more complex, check if there is already a
  67 helper method, they are also good examples.
  68
  69 Helper methods which are used by more than one testsuite are in the
  70 `SwModelTestBase` class. For example the `getLength()` method uses the trick
  71 that you can simply enumerate over the document model, getting the paragraphs
  72 of it; and inside those, you can enumerate over their runs. That alone is
  73 enough if you want to test a paragraph or character property.
  74
  75 == Using UNO for tests
  76
  77 Figuring out the UNO API just by reading the idl files under `offapi/` is not
  78 that productive. Xray can help in this case. Download it from:
  79
  80 https://dev-www.libreoffice.org/extern/XrayTool52_en.sxw
  81
  82 It's a document file, start Writer, Tools -> Options -> LibreOffice -> Security,
  83 Macro Security, and there choose Low. Then open the document, and click `Install
  84 Xray`. Now you can close the file. Open your testcase, which is imported
  85 correctly (from a fixed bugs's point of view). Then open the basic editor
  86 (Tools -> Macros -> LibreOffice Basic -> Organize Macros, Edit), and start to
  87 write your testcase as `Sub Main`. You don't have to know much about basic, for
  88 a typical testcase you need no `if`, `for`, or anything like that.
  89
  90 NOTE: Once you restart Writer, xray will no longer be loaded automatically. For
  91 subsequent starts, place the following line in `Main` before you do anything
  92 else:
  93
  94 ----
  95 GlobalScope.BasicLibraries.LoadLibrary("XrayTool")
  96 ----
  97
  98 The above `mxComponent` is available as `ThisComponent` in basic, and if you
  99 want to inspect a variable here, you can use the `xray` command to inspect
 100 properties, methods, interfaces, etc.
 101
 102 Let's take for example fdo#49501. The problem there was the page was not
 103 landscape (and a few more, let's ignore that).
 104
 105 You can start with:
 106
 107 ----
 108 xray ThisComponent
 109 ----
 110
 111 and navigate around (it is a good idea to click Configuration and enable
 112 alphabetical sorting). The good thing is that once you write the code, you can
 113 just start F5 without restarting LibreOffice to see the result, so you can
 114 develop quickly.
 115
 116 With some experimenting, you'll end up with something like this:
 117
 118 ----
 119 oStyle = ThisComponent.StyleFamilies.PageStyles.getByName("Default Style")
 120 xray oStyle.IsLandscape
 121 ----
 122
 123 Now all left is to rewrite that in cpp, where it'll be much easier to debug
 124 when later this test fails for some reason. In cpp, you typically need to be
 125 more verbose, so the code will look like:
 126
 127 ----
 128 uno::Reference<beans::XPropertySet> xStyle(getStyles("PageStyles")->getByName("Standard"), uno::UNO_QUERY);
 129 CPPUNIT_ASSERT_EQUAL(true, getProperty<bool>(xStyle, "IsLandscape"));
 130 ----
 131
 132 == CppUnit tips
 133
 134 === sal_Bool
 135
 136 In case a UNO method returns sal_Bool, and the assert fails, CppUnit won't be
 137 able to print a usable error message, as it will think that the value is a
 138 printable character. Best to use `bool` for the expected value and cast the
 139 actual value to `bool` as well before comparing.
 140
 141 === Running only a single test
 142
 143 If you want to run only a single test to allow quick development iteration,
 144 then use `CPPUNIT_TEST_NAME` to specify the name of the single test:
 145
 146 ----
 147 CPPUNIT_TEST_NAME="testTdf91074" make -sr CppunitTest_sw_rtfexport6
 148 ----
 149
 150 == UNO, in more details, various tips:
 151
 152 === writing code based xray inspection:
 153
 154 In general, if you want to access a property, in Basic it's enough to write 'object.property',
 155 such as printing character count that 'xray ThisComponent' prints as 'CharacterCount':
 156
 157 count = ThisComponent.CharacterCount
 158 text = paragraph.String
 159
 160 In C++, this can get more complicated, as you need to use the right interface for access. Xray
 161 prints the internal name of the object (e.g. 'SwXTextDocument' for 'xray ThisComponent')
 162 above the list of its properties. Inspect this class/interface in the code (that is,
 163 under offapi/, udkapi/, or wherever it is implemented) and search for a function named
 164 similarly to the property you want (getXYZ()). If there is none, it is most
 165 probably a property that can be read using XPropertySet or using the getProperty helper:
 166
 167 sal_Int32 val = getProperty< sal_Int32 >( textDocument, "CharacterCount" );
 168
 169 If there is a function to obtain the property, you need access it using the right interface.
 170 If the class itself is not the right interface, then it is one of the classes it inherits
 171 from, usually the block of functions that are implemented for this interface starts with
 172 stating the name. For example see sw/inc/unoparagraph.hxx for class SwXParagraph, it has
 173 function getString() in a block introduced with 'XTextRange', so XTextRange is the interface
 174 it inherits from:
 175
 176 // text of the paragraph
 177 uno::Reference<text::XTextRange> text(paragraph, uno::UNO_QUERY);
 178 OUString value = text->getString();
 179
 180 Some properties may be more complicated to access, such as using XEnumerationAccess, XIndexAccess
 181 or XNamedAccess to enumerate items, index them by number of name (clicking 'Dbg_SupportedInterfaces'
 182 in xray gives a list of interfaces the object implements, and 'Count' shows the number of items).
 183
 184 === XEnumerationAccess (e.g. get the 2nd paragraph of the document):
 185
 186 Basic:
 187
 188 enum = ThisComponent.Text.createEnumeration
 189 para = enum.NextElement
 190 para = enum.NextElement
 191 xray para
 192
 193 C++:
 194
 195 uno::Reference<text::XTextDocument> textDocument(mxComponent, uno::UNO_QUERY);
 196 uno::Reference<container::XEnumerationAccess> paraEnumAccess(textDocument->getText(), uno::UNO_QUERY);
 197 // list of paragraphs
 198 uno::Reference<container::XEnumeration> paraEnum = paraEnumAccess->createEnumeration();
 199 // go to 1st paragraph
 200 (void) paraEnum->nextElement();
 201 // get the 2nd paragraph
 202 uno::Reference<uno::XInterface> paragraph(paraEnum->nextElement(), uno::UNO_QUERY);
 203
 204 Note that for paragraphs it's easier to use getParagraph(), which gets the given
 205 paragraph (counted from 1) and optionally checks the paragraph text.
 206
 207 uno::Reference< text::XTextRange > paragraph = getParagraph( 2, "TEXT" )
 208
 209 === XNamedAccess (e.g. get a bookmark named 'position1'):
 210
 211 Basic:
 212
 213 bookmark = ThisComponent.Bookmarks.getByName("position1")
 214
 215 or even simpler
 216
 217 bookmark = ThisComponent.Bookmarks.position1
 218
 219 C++:
 220
 221 uno::Reference<text::XTextDocument> textDocument(mxComponent, uno::UNO_QUERY);
 222 // XBookmarksSupplier interface will be needed to access the bookmarks
 223 uno::Reference<text::XBookmarksSupplier> bookmarksSupplier(textDocument, uno::UNO_QUERY);
 224 // get the bookmarks
 225 uno::Reference<container::XNameAccess> bookmarks(bookmarksSupplier->getBookmarks(), uno::UNO_QUERY);
 226 uno::Reference<uno::XInterface> bookmark;
 227 // get the bookmark by name
 228 bookmarks->getByName("position1") >>= bookmark;
 229
 230 === XIndexAccess (e.g. get the first bookmark):
 231
 232 Basic:
 233
 234 bookmark = ThisComponent.Bookmarks.getByIndex(0)
 235
 236 C++:
 237
 238 uno::Reference<text::XTextDocument> textDocument(mxComponent, uno::UNO_QUERY);
 239 // XBookmarksSupplier interface will be needed to access the bookmarks
 240 uno::Reference<text::XBookmarksSupplier> bookmarksSupplier(textDocument, uno::UNO_QUERY);
 241 // get the bookmarks
 242 uno::Reference<container::XIndexAccess> bookmarks(bookmarksSupplier->getBookmarks(), uno::UNO_QUERY);
 243 uno::Reference<uno::XInterface> bookmark;
 244 // get the bookmark by index
 245 bookmarks->getByIndex(0) >>= bookmark;
 246
 247 === Images
 248
 249 Embedded images seem to be accessed like this:
 250
 251 Basic:
 252
 253 image = ThisComponent.DrawPage.getByIndex(0)
 254 graphic = image.Graphic
 255
 256 C++:
 257
 258 uno::Reference<drawing::XShape> image = getShape(1);
 259 uno::Reference<graphic::XGraphic> graphic = getProperty< uno::Reference< graphic::XGraphic > >( image, "Graphic" );
 260
 261
 262 === Styles
 263
 264 Styles provide information about many properties of (parts of) the document, for example
 265 page width:
 266
 267 Basic:
 268
 269 ThisComponent.StyleFamilies.PageStyles.getByName("Default Style").Width
 270
 271 C++:
 272
 273 getStyles("PageStyles")->getByName("Standard") >>= defaultStyle;
 274 sal_Int32 width = getProperty< sal_Int32 >( defaultStyle, "Width" );