1================================================= 2:mod:`PyObjCTools.TestSupport` -- Testing helpers 3================================================= 4 5.. module:: PyObjCTools.TestSupport 6 :synopsis: Testing helpers 7 8This module provides classes and functions that are 9usefull for testing PyObjC itself including the framework 10wrappers. 11 12.. warning:: 13 14 This module is primarily used for testing PyObjC 15 and the API isn't fully stable. 16 17 18.. function:: sdkForPython() 19 20 Returns the SDK version used to compile Python, 21 or :data:`None` when no version can be calculated. 22 23 The SDK version is a tupel with the major 24 and minor versions of Mac OS X (for example ``(10, 8)``). 25 26.. function:: fourcc(value) 27 28 Returns the integer value of a four character code 29 "literal". 30 31 The *value* is a byte string of length 4 and contains 32 the contents of the :c:type:`char` C literal with 33 the four character code, for example ``b"abcd"``. 34 35.. function:: cast_int(value) 36 37 Return *value* as if it were a 4 byte integer (using 38 the overflow behavior of most CPUs) 39 40.. function:: cast_longlong(value) 41 42 Return *value* as if it were a 8 byte integer (using 43 the overflow behavior of most CPUs) 44 45 46.. function:: cast_uint(value) 47 48 Return *value* as if it were a 4 byte unsigned integer ( 49 using the overflow behavior of C) 50 51.. function:: cast_ulonglong(value) 52 53 Return *value* as if it were a 8 byte unsigned integer (using 54 the overflow behavior of C) 55 56.. function:: os_release() 57 58 Returns the major release of Mac OS X on the current machine, 59 for example "10.5" on all systems running a version 60 of Leopard. 61 62.. function:: is32Bit() 63 64 Returns :data:`True` if the proces is in 32-bit mode. 65 66.. function:: onlyIf(expr, message) 67 68 Decorator for enabling tests only when an expression is true. This is 69 the same as :func:`skipUnless <unittest.skipUnless>` in Python 2.7 or later. 70 71.. function:: onlyPython2 72 73 Decorator for enabling a test only when using Python 2.x. 74 75 This is basicly ``onlyIf(sys.version_info[0] == 2)``. 76 77.. function:: onlyPython3 78 79 Decorator for enabling a test only when using Python 3.x. 80 81 This is basicly ``onlyIf(sys.version_info[0] == 3)``. 82 83.. function:: onlyOn32Bit 84 85 Decorator for enabling a test only when the process is running in 32-bit mode. 86 87.. function:: onlyOn64Bit 88 89 Decorator for enabling a test only when the process is running in 64-bit mode. 90 91.. function:: min_os_level(version) 92 93 Decorator for enabling a test only when running on a recent enough release 94 of Mac OS X. 95 96 97.. function:: max_os_level(version) 98 99 Decorator for enabling a test only when running on a old enough release 100 of Mac OS X. 101 102.. class:: filterWarnings(kind, category) 103 104 A with-statement context that adds a filter to the warnings module 105 while the body of the statement is running. 106 107 This is similar to :class:`warnings.catch_warnings`. 108 109 110.. _`leaks(1)`: https://developer.apple.com/library/mac/#documentation/Darwin/Reference/ManPages/man1/leaks.1.html 111 112.. class:: TestCase 113 114 A subclass of :class:`unittest.TestCase` with some addition functionality. The 115 most important addition is that each test gets run with a fresh autorelease pool. 116 117 .. method:: run() 118 119 Calls :meth:`unitest.TestCase.run`, but ensures that there is a fresh 120 autorelease pool for every test. This makes is less likely that two 121 tests accidenty influence each other. 122 123 There will not be a fresh autorelease pool when :envvar:`PYOBJC_NO_AUTORELEASE` 124 is in the shell environment. 125 126 127 .. versionchanged:: 2.5 128 Removed support for using the `leaks(1)`_ tool to check for memory leaks because 129 that support was broken (cause test hangs) and didn't properly report leaks. This 130 used to environment variable :envvar:`PyOBJC_USE_LEAKS` as a trigger to enable the 131 functionality. 132 133 .. method:: assertItemsEqual(seq1, seq2[, message]) 134 135 Asserts that sequences *seq1* and *seq2* have the same members (in any order). 136 137 .. method:: assertGreaterThan(value, test[, message]) 138 139 Asserts that *value* is greater than *test*. 140 141 .. method:: assertGreaterThanOrEquals(value, test[, message]) 142 143 Asserts that *value* is greater than or equal to *test*. 144 145 .. method:: assertLessThan(value, test[, message]) 146 147 Asserts that *value* is less than *test*. 148 149 .. method:: assertLessThanOrEquals(value, test[, message]) 150 151 Asserts that *value* is less than or equal to *test*. 152 153 .. method:: assertIs(value, test[, message]) 154 155 Asserts that *value* is the same object as *test* 156 157 .. method:: assertIsNot(value, test[, message]) 158 159 Asserts that *value* is not the same object as *test* 160 161 .. method:: assertIsNone(value[, message]) 162 163 Asserts that *value* is the same object as :data:`None` 164 165 .. method:: assertIsNotNone(value[, message]) 166 167 Asserts that *value* is the not same object as :data:`None` 168 169 .. method:: assertSstartswith(self, value, check[, message]) 170 171 Assert that *value* is a string that starts with *check*. 172 173 .. method:: assertHasAttr(self, value, key[, message]) 174 175 Assert that *value* has an attribute named *key*. 176 177 .. method:: assertNotHasAttr(self, value, key[, message]) 178 179 Assert that *value* does not have an attribute named *key*. 180 181 .. method:: assertIsInstance(self, value, types[, message]) 182 183 Assert that *value* is an instance of *types*. 184 185 .. method:: assertIsNotInstance(self, value, types[, message]) 186 187 Assert that *value* is not an instance of *types*. 188 189 .. method:: assertAlmostEquals(val1, val2[, message) 190 191 Assert that *val1* is almost equal to *val2* (that is, 192 the difference between the two values is less that 1e-5) 193 194 .. method:: assertIn(self, value, seq[, message]) 195 196 Assert that *value* is a member of *seq*. 197 198 .. method:: assertNotIn(self, value, seq[, message]) 199 200 Assert that *value* is not a member of *seq*. 201 202 .. method:: assertIsCFType(tp[, message]) 203 204 Asserts that *tp* is a wrapper class for a CoreFoundation type. 205 206 .. method:: assertIsOpaquePointer(tp[, message) 207 208 Asserts that *tp* is a wrapper class for an opaque pointer ("handle") 209 210 .. method:: assertIsNullTerminated(method[, message]) 211 212 Asserts that the callable has metadata that indicates that the 213 callable is variadic function where the argument list is terminated by 214 a null value. 215 216 .. method:: assertResultIsNullTerminated(method[, message]) 217 218 Asserts that the callable has metadata that indicates that the result 219 is a null terminated array. 220 221 .. method:: assertArgIsNullTerminated(method, argno[, message]) 222 223 Asserts that the callable has metadata that indicates that the argument 224 *argno* is a null terminated array. 225 226 227 .. method:: assertResultIsVariableSize(method[, message]) 228 229 Asserts that the callable has metadata that indicates that the result 230 is an array with an unspecified size. 231 232 .. method:: assertArgIsVariableSize(method, argno[, message]) 233 234 Asserts that the callable has metadata that indicates that the argument 235 *argno* is an array with an unspecified size. 236 237 .. method:: assertArgSizeInResult(method, argno[, message) 238 Asserts that the callable has metadata that indicates that the argument 239 *argno* is an array where the size of the array is specified in the return value. 240 241 .. method:: assertArgIsPrintf(method, argno[, message]) 242 243 Assert that the callable has metadata that specifies that it is a 244 variadic function with a printf-format string in argument *argno*. 245 246 .. method:: assertResultIsCFRetained(method[, message]) 247 248 Assert that the callable has metadata that specifies that the 249 retain count of the result is increased by the function (that 250 is, the caller owns the value after the call). 251 252 .. method:: assertResultIsNotCFRetained(method[, message]) 253 254 Assert that the callable has metadata that specifies that the 255 retain count of the result is not increased by the function. 256 257 .. method:: assertArgIsCFRetained(method, argno[, message]) 258 259 Assert that the callable has metadata that specifies that the 260 retain count of argument *argno* is increased by the function (that 261 is, the caller owns the value after the call). 262 263 .. note:: used to check the behavior of output arguments. 264 265 .. method:: assertArgIsNotCFRetained(method, argno[, message]) 266 267 Assert that the callable has metadata that specifies that the 268 retain count of argument *argno* is not increased by the function. 269 270 .. note:: used to check the behavior of output arguments. 271 272 .. method:: assertResultIsRetained(method[, message]) 273 274 Assert that the callable has metadata that specifies that the 275 retain count of the result is increased by the function (that 276 is, the caller owns the value after the call). 277 278 .. method:: assertResultIsNotRetained(method[, message]) 279 280 Assert that the callable has metadata that specifies that the 281 retain count of the result is not increased by the function. 282 283 .. method:: assertArgIsRetained(method, argno[, message]) 284 285 Assert that the callable has metadata that specifies that the 286 retain count of argument *argno* is increased by the function (that 287 is, the caller owns the value after the call). 288 289 .. note:: used to check the behavior of output arguments. 290 291 .. method:: assertArgIsNotRetained(method, argno[, message]) 292 293 Assert that the callable has metadata that specifies that the 294 retain count of argument *argno* is not increased by the function. 295 296 .. note:: used to check the behavior of output arguments. 297 298 .. method:: assertResultHasType(method, tp[, message]) 299 300 Assert that the result has a specific type encoding. 301 302 .. method:: assertResultIsBOOL(method[, message]) 303 304 Assert that the result has type :c:type:`BOOL`. 305 306 .. method:: assertArgHasType(method, argno, tp[, message]) 307 308 Assert that the argument *argno* has a specific type encoding. 309 310 .. method:: assertArgIsBOOL(method, argno[, message]) 311 312 Assert that the argument *argno* has type :c:type:`BOOL`. 313 314 .. method:: assertArgIsFunction(method, argno, sel_type, retained[, message]) 315 316 Assert that argument *argno* is a function with a specific type signature. 317 If *retained* is true the function stores the function reference beyond 318 the end of the function call. 319 320 .. method:: assertResultsFunction(method, sel_type, [, message]) 321 322 Assert that the result is a function with a specific type signature. 323 324 .. method:: assertResultIsBlock(method, sel_type[, message]) 325 326 Assert that the result is a block with a specific type signature. 327 328 .. method:: assertArgIsBlock(method, argno, sel_type[, message]) 329 330 Assert that argument *argno* is a block with a specific type signature. 331 332 .. method:: assertArgIsSEL(method, argno, sel_type[, message]) 333 334 Assert that argument *argno* is a SEL value for a method with 335 a specific type signature 336 337 .. method:: assertArgIsFixedSize(method, argno, count[, message]) 338 339 Assert that argument *argno* is an array of *count* elements. 340 341 .. method:: assertResultSizeInArg(method, count[, message]) 342 343 Assert that the result is an array of where the size 344 of the array is specified in argument *count*. 345 346 .. method:: assertArgSizeInArg(method, argno, count[, message]) 347 348 Assert that argument *argno* is an array of where the size 349 of the array is specified in argument *count*. 350 351 *count* can also be an tuple of two elements: the first elements 352 specifies the size before the call, the second the size 353 after the call. 354 355 .. method:: assertArgIsOut(method, argno[, message]) 356 357 Assert that argument *argno* is a pass-by-reference output parameter. 358 359 .. method:: assertArgIsIn(method, argno[, message]) 360 361 Assert that argument *argno* is a pass-by-reference input parameter. 362 363 .. method:: assertArgIsInOut(method, argno[, message]) 364 365 Assert that argument *argno* is a pass-by-reference input and output parameter. 366 367 .. note:: 368 369 There are also a number of deprecated aliases for the methods above, those 370 are intentionally not documented. 371