tests/tests-readme.txt

   1 \r
   2 Welcome to the Irrlicht test suite.\r
   3 ===================================\r
   4 This is composed of a series of tests which exercise basic Irrlicht\r
   5 functionality.  These are not strictly unit tests, since there is no stub\r
   6 framework that isolates each method under test.  They do however test small\r
   7 units of functionality and should help to isolate problems and spot\r
   8 regressions.\r
   9 \r
  10 You are encouraged to run the tests whenever you make any significant code\r
  11 change, and to add tests for any new or modified area of code.\r
  12 \r
  13 The overall test application will return a count of the number of tests that\r
  14 failed, i.e. 0 is success.  It will also log to tests/tests.log file, and on\r
  15 success will update the tests/tests-last-passed-at.txt file (which gets\r
  16 committed with code changes as a very basic verification that we're not\r
  17 regressing).\r
  18 \r
  19 \r
  20 Working directory\r
  21 =================\r
  22 Since the tests rely on the presence of /media and /empty/empty subdirectories,\r
  23 the working directory must be the /tests directory, not /bin/$PLATFORM. This\r
  24 means that you cannot run /bin/$PLATFORM/texts.exe from there.  You can however\r
  25 cd to /tests and run ../bin/$PLATFORM/tests.exe\r
  26 \r
  27 \r
  28 Adding a new test\r
  29 =================\r
  30 To add a new test, e.g. "myNewTest":\r
  31 \r
  32 1) Create tests/myNewTest.cpp.  At a minimum, this must contain a function with\r
  33    the signature bool fnName(void), where fnName is the same as the filename\r
  34    (without the .cpp suffix).\r
  35 \r
  36    This function must return true if the tests passes, or false if it fails. In\r
  37    this example, the function should be:\r
  38 \r
  39    bool myNewTest(void)\r
  40    {\r
  41    ...\r
  42    }\r
  43 \r
  44 2) Add myNewTest.cpp to the build targets in tests.cbp, tests_vc8.vcproj and\r
  45    tests_vc9.vcproj.  These are all text files that can be edited manually by\r
  46    hand; just copy, paste and modify an existing source file entry.\r
  47 \r
  48 3) In tests/main.cpp, find the list of TEST() macro calls, and add a call to\r
  49    your new test, using the TEST macro, e.g.:\r
  50 \r
  51    TEST(myNewTest);\r
  52 \r
  53 4) Run your test, and verify any images that it produces (see "Screenshots").\r
  54 \r
  55 5) Remember to svn add tests/newNewTest.cpp and any new tests/media/ files.\r
  56 \r
  57 Your test will be run independently in its own indepedent process. It is\r
  58 responsible for creating any required resources or Irrlicht interfaces, and for\r
  59 cleaning up after itself and restoring the working directory to /tests.  You do\r
  60 not have to link against Irrlicht.lib; the whole application is already linked\r
  61 to it.\r
  62 \r
  63 \r
  64 Logging\r
  65 =======\r
  66 Please use logTestString() to log any interesting output or fails from your\r
  67 test.  This is declared in tests/testUtils.h.  Its output goes to\r
  68 tests/tests.log\r
  69 \r
  70 \r
  71 Screenshots\r
  72 ===========\r
  73 testUtils.h/.cpp provides a function to create a screenshot and compare it with\r
  74 a reference image.  This is useful for validating new or changed functionality,\r
  75 and for catching regressions.\r
  76 \r
  77 Call the unambiguously named takeScreenshotAndCompareAgainstReference()\r
  78 function to do this. It needs an IVideoDriver (which it will use to create the\r
  79 first part of the filename) and a unique filename including an image format\r
  80 suffix, e.g. "-myNewTest.png".  You should use .png as a suffix unless you have\r
  81 a very specific need to use another format.  Please avoid using .jpg as image\r
  82 compression can introduce artifacts and false fails.\r
  83 \r
  84 Optionally, you can specify the amount of match that is required between the\r
  85 produced screenshot and the reference image.  While the images should match\r
  86 exactly, we have found that OpenGL implementations can vary significantly\r
  87 across test machines, often around 99% match (of total colour values across all\r
  88 pixels).  You may have to go as low as 98% for some images, but please try to\r
  89 err on the side of strictness until we can determine that your test image needs\r
  90 to be fuzzier on other peoples' machines.\r
  91 \r
  92 If takeScreenshotAndCompareAgainstReference() can't find an existing reference\r
  93 image, it will create one from the screenshot.  In effect, this means that you\r
  94 have to run your test once (expecting it to fail) in order to produce the\r
  95 initial reference images.  The new images are created in tests/results with\r
  96 filename:\r
  97 \r
  98 driverName-filename.suffix\r
  99 \r
 100 e.g. OpenGL-myNewTest.png (note that the OpenGL driver elides the actual OpenGL\r
 101 version number from the filename, as this tends to differ between machines and\r
 102 installations).\r
 103 \r
 104 You should check these new images carefully to ensure that they show exactly\r
 105 what you expect.  Please do not just assume that they do, as validating bad\r
 106 behaviour is worse than not validating it at all!\r
 107 \r
 108 If the images do appear exactly as you expect, move them to the tests/media\r
 109 directory, and re-run the tests.  They should now pass.  Remember to svn add\r
 110 any new media files!\r
 111 \r
 112 \r
 113 What to do when the tests fail\r
 114 ==============================\r
 115 DON'T PANIC!\r
 116 \r
 117 This is a Good Thing.  Failing tests challenge our assumptions and help us to\r
 118 make Irrlicht more robust.\r
 119 \r
 120 First, check your working directory.  The tests need to be run from the tests/\r
 121 directory, not a /bin subdirectory.  You can do this using the working\r
 122 directory in your debugger, or on the command line by running the tests\r
 123 executable (wherever it is build) from the tests/ directory.\r
 124 \r
 125 If you need to debug a test, first move it temporarily to the start of the list\r
 126 of TEST() macros. This is because each test runs in its own process, so only\r
 127 the first test will have the debugger attached.\r
 128 \r
 129 If the fail is due to a bitmap difference, carefully compare the bitmaps, and\r
 130 the amount of failure. The OpenGL device does tend to produce differences.  You\r
 131 should not just automatically make a test fuzzier, but if you can rule out any\r
 132 real issue in the code, it can be valid to accept OpenGL image matches as low\r
 133 as 98%.  Other devices should not require this amount of fuzziness!\r
 134 \r
 135 If you can't figure out the reason for the failure (or better yet, if you can,\r
 136 and think the tests and/or Irrlicht need updated), then please do raise the\r
 137 issue in the bug forum:\r
 138 \r
 139 http://irrlicht.sourceforge.net/phpBB2/viewforum.php?f=7\r
 140 \r
 141 We do want to hear about fails, and will thank you for finding them.\r
 142 \r
 143 Running specific tests\r
 144 ======================\r
 145 The app takes two parameters. First is the test to start with (starting at 0\r
 146 anddefaulting to 0), the second is the number of tests to run (beginning with\r
 147 the one given as first parameter). If the second parameter is not given, all\r
 148 existing tests are run (again starting with the first parameter). So, starting\r
 149 the test suite without a parameter will really run all tests.  Another special\r
 150 parameter is '--list', which outputs a list of all existing tests and their\r
 151 respective number.\r
 152 \r
 153 For debugging purposes it can make sense to run a test without spawning a\r
 154 separate process for each test case. This can be switched off by a boolean flag\r
 155 in main.cpp ('spawn=false').\r
 156 \r
 157 Currently implemented tests\r
 158 ===========================\r
 159 000. disambiguateTextures\r
 160 001. testIrrArray\r
 161 002. testIrrMap\r
 162 003. testIrrList\r
 163 004. exports\r
 164 005. irrCoreEquals\r
 165 006. testIrrString\r
 166 007. testLine2d\r
 167 008. matrixOps\r
 168 009. testDimension2d\r
 169 010. testVector2d\r
 170 011. testVector3d\r
 171 012. testQuaternion\r
 172 013. testS3DVertex\r
 173 014. testaabbox3d\r
 174 015. color\r
 175 016. testTriangle3d\r
 176 017. vectorPositionDimension2d\r
 177 018. filesystem\r
 178 019. archiveReader\r
 179 020. testXML\r
 180 021. serializeAttributes\r
 181 022. fast_atof\r
 182 023. loadTextures\r
 183 024. collisionResponseAnimator\r
 184 025. enumerateImageManipulators\r
 185 026. removeCustomAnimator\r
 186 027. sceneCollisionManager\r
 187 028. sceneNodeAnimator\r
 188 029. meshLoaders\r
 189 030. testTimer\r
 190 031. softwareDevice\r
 191 032. b3dAnimation\r
 192 033. burningsVideo\r
 193 034. billboards\r
 194 035. createImage\r
 195 036. cursorSetVisible\r
 196 037. flyCircleAnimator\r
 197 038. guiDisabledMenu\r
 198 039. makeColorKeyTexture\r
 199 040. md2Animation\r
 200 041. meshTransform\r
 201 042. skinnedMesh\r
 202 043. testGeometryCreator\r
 203 044. writeImageToFile\r
 204 045. ioScene\r
 205 046. videoDriver\r
 206 047. screenshot\r
 207 048. drawPixel\r
 208 049. drawRectOutline\r
 209 050. drawVertexPrimitive\r
 210 051. material\r
 211 052. renderTargetTexture\r
 212 053. textureFeatures\r
 213 054. textureRenderStates\r
 214 055. transparentMaterials\r
 215 056. userclipplane\r
 216 057. antiAliasing\r
 217 058. draw2DImage\r
 218 059. lights\r
 219 060. twodmaterial\r
 220 061. viewPort\r
 221 062. mrt\r
 222 063. projectionMatrix\r
 223 064. planeMatrix\r
 224 065. terrainSceneNode\r
 225 066. lightMaps\r
 226 067. triangleSelector\r
 227 \r