/packages/fcl-xml/tests/README_DOM.txt

https://github.com/slibre/freepascal · Plain Text · 89 lines · 65 code · 24 blank · 0 comment · 0 complexity · 3a575156a444e110479253e2c88c670e MD5 · raw file

  1. Testing FCL DOM implementation with official test suite from w3.org
  2. -------------------------------------------------------------------
  3. *** IMPORTANT: READ CAREFULLY!
  4. IF YOU ARE ABOUT TO RUN THESE TESTS, CONSIDER DOING SO IN AN ENVIRONMENT
  5. THAT YOU MAY ALLOW TO BE TRASHED.
  6. As of writing this at 3 June 2008, FCL DOM memory model is
  7. not compatible - at all - with the way that w3.org tests use. In
  8. particular, tests acquire (and use) references to objects that DOM
  9. implementation frees. Therefore, running the tests WILL result in heap
  10. corruption, executing arbitrary code, and any other imaginable kind of
  11. disaster. Be warned.
  12. [Update: This was fixed in SVN revision 13196, dated 26 May 2009.]
  13. *** End of notice
  14. --------------------------------------------------------------------
  15. The fcl-xml package support for testing its DOM implementation consists of
  16. the following files:
  17. 1) testgen.pp - an utility for generating Pascal source from XML descriptions.
  18. 2) api.xml - database used by testgen.
  19. 3) domunit.pp - FPCUnit extensions required at runtime.
  20. 4) extras.pp - Additional tests, not present in w3.org testsuite.
  21. 5) extras2.pp - Some tests that are present in the testsuite, but converted/modified
  22. by hand because automatic conversion is not yet possible.
  23. 6) README_DOM.txt - this file.
  24. To test the FCL DOM implementation, follow these steps:
  25. 1) Checkout the DOM test suite from w3.org CVS repository. The project name is
  26. 2001/DOM-Test-Suite. Only 'tests' subdirectory is needed, everything else
  27. is irrelevant for our purposes.
  28. Use the following commands:
  29. CVSROOT=:pserver:anonymous@dev.w3.org:/sources/public
  30. cvs login
  31. (enter the password anonymous when prompted)
  32. cvs checkout 2001/DOM-Test-Suite/tests
  33. 2) Compile the testgen utility. A simple
  34. fpc testgen.pp
  35. should do it.
  36. 3) Use testgen to convert DOM test suites into Pascal code. Specify path to the
  37. directory that contains 'alltests.xml' file, and the name of resulting FPC unit.
  38. Testgen expects the API description file 'api.xml' present in its directory.
  39. Successful conversion of the following test modules is possible:
  40. Level 1 Core (527 tests):
  41. testgen 2001/DOM-Test-Suite/tests/level1/core core1.pp
  42. Level 2 Core (282 tests):
  43. testgen 2001/DOM-Test-Suite/tests/level2/core core2.pp
  44. Level 2 HTML (677 out of 685 tests, only conversion -- not runnable yet):
  45. testgen 2001/DOM-Test-Suite/tests/level2/html html2.pp
  46. Level 3 Core (partial only, 131 out of 722 tests):
  47. testgen 2001/DOM-Test-Suite/tests/level3/core core3.pp
  48. Level 3 XPath (63 tests, only conversion -- not runnable yet):
  49. testgen 2001/DOM-Test-Suite/tests/level3/xpath xpath3.pp
  50. In the examples above, output names (core1.pp, etc.) carry no defined meaning, except
  51. they are used to construct test names which appear in the test reports. The test name
  52. is constructed from the unit name by removing the extension and adding a 'TTest' prefix.
  53. Normally, tests that contain properties/methods unsupported by FCL DOM, or
  54. other elements not yet known to testgen, will be skipped. The conversion may be forced
  55. by using -f commandline switch, but in this case the resulting Pascal unit will likely
  56. fail to compile.
  57. 4) Now, pick up your preferred fpcunit test runner, add the generated units to its
  58. uses clause, and compile. You may as well add the suppied 'extras.pp' and 'extras2.pp'
  59. units. During compilation, path to 'domunit.pp' should be added to the unit search
  60. paths.
  61. 5) During runtime, tests must be able to read test files which are located
  62. within CVS source tree ('files' subdirectory of each module directory). For this purpose,
  63. each generated test class contains a function 'GetTestFilesURI' which returns the path
  64. that was supplied to testgen. Therefore, either use an absolute path, or ensure that both
  65. generated sources and the test executable are located in the same directory.