API#

Python API#

Test Cases

StandaloneDocTestCase

Base class for all standalone test cases with doctest support for checking docstrings examples.

AsyncDocTestCase

Base class for all async test cases with doctest support for checking docstrings examples.

Test Cases#

class AsyncDocTestCase(*args: Any, **kwargs: Any)#

Bases: AsyncTestCase

Base class for all async test cases with doctest support for checking docstrings examples.

This class provides methods to validate that code examples in docstrings execute correctly. It is designed for Kit-based async test environments and inherits from omni.kit.test.AsyncTestCase.

Note

Derive from it to make the tests auto discoverable. Test methods must start with the test_ prefix.

This class adds the following methods:

  • assertDocTest: Check that the examples in docstrings pass for a class/module member.

  • assertDocTests: Check that the examples in docstrings pass for all class/module’s members.

Available Doctest Directives:

Use these directives in docstring examples to control test behavior:

  • # doctest: +NO_CHECK: Run the example but skip output verification.

  • # doctest: +SKIP: Skip this example entirely (don’t run it).

  • # doctest: +ELLIPSIS: Allow ... in expected output to match any substring.

  • # doctest: +NORMALIZE_WHITESPACE: Ignore whitespace differences.

Creating a Test File:

To test docstrings for an extension module or class, create a test file like this:

# test_docstrings.py
from isaacsim.test.docstring import AsyncDocTestCase
import my_extension_module

class TestDocstrings(AsyncDocTestCase):
    async def test_my_module_docstrings(self):
        # Test all members of a module
        await self.assertDocTests(my_extension_module)

    async def test_single_function(self):
        # Test a specific function (sync method)
        self.assertDocTest(my_extension_module.some_function)

    async def test_with_options(self):
        # Test with custom options
        await self.assertDocTests(
            my_extension_module.MyClass,
            exclude=[my_extension_module.MyClass.internal_method],
            stop_on_failure=True,  # Stop at first failure
            await_update=True,  # Await Kit update between tests
        )

Example:

>>> import isaacsim.test.docstring
>>> tester = isaacsim.test.docstring.AsyncDocTestCase()
>>> tester.__class__.__name__
'AsyncDocTestCase'
Parameters:

  • *args – Variable positional arguments passed to the parent class.

  • **kwargs – Additional keyword arguments passed to the parent class.

assertDocTest(
expr: object,
msg: str = '',
flags: int = 1036,
)#

Check that the examples in docstrings pass for a class/module member.

Parameters:

  • expr – Module function or class definition, property or method to check docstrings examples for.

  • msg – Custom message to display when failing.

  • flags – Doctest option flags.

Example:

>>> from isaacsim.test.docstring import AsyncDocTestCase
>>>
>>> tester.assertDocTest(AsyncDocTestCase)
async assertDocTests(
expr: object,
msg: str = '',
flags: int = 1036,
order: list[tuple[object, int]] = [],
exclude: list[object] = [],
stop_on_failure: bool = False,
await_update: bool = True,
)#

Check that the examples in docstrings pass for all class/module’s members (names).

Parameters:

  • expr – Module or class definition to check members’ docstrings examples for.

  • msg – Custom message to display when failing.

  • flags – Doctest option flags.

  • order – List of pair (name, index) to modify the examples execution order.

  • exclude – List of class/module names to exclude for testing.

  • stop_on_failure – Stop testing docstrings example at first encountered failure.

  • await_update – Await next kit application update async before running each docstrings example.

Example:

>>> from isaacsim.test.docstring import AsyncDocTestCase
>>> from omni.kit.async_engine import run_coroutine
>>>
>>> async def task():
...     await tester.assertDocTests(AsyncDocTestCase, exclude=[AsyncDocTestCase.assertDocTests])
...
>>> run_coroutine(task())
class StandaloneDocTestCase(*args, **kwargs)#

Bases: TestCase

Base class for all standalone test cases with doctest support for checking docstrings examples.

This class provides methods to validate that code examples in docstrings execute correctly. It is designed for standalone (non-Kit) test environments using Python’s unittest framework.

Note

Test methods must start with the test_ prefix.

This class adds the following methods:

  • assertDocTest: Check that the examples in docstrings pass for a class/module member.

  • assertDocTests: Check that the examples in docstrings pass for all class/module’s members.

Available Doctest Directives:

Use these directives in docstring examples to control test behavior:

  • # doctest: +NO_CHECK: Run the example but skip output verification.

  • # doctest: +SKIP: Skip this example entirely (don’t run it).

  • # doctest: +ELLIPSIS: Allow ... in expected output to match any substring.

  • # doctest: +NORMALIZE_WHITESPACE: Ignore whitespace differences.

Creating a Test File:

To test docstrings for a module or class, create a test file like this:

# test_docstrings.py
import unittest
from isaacsim.test.docstring import StandaloneDocTestCase
import my_module

class TestDocstrings(StandaloneDocTestCase):
    def test_my_module_docstrings(self):
        # Test all members of a module
        self.assertDocTests(my_module)

    def test_single_function(self):
        # Test a specific function
        self.assertDocTest(my_module.some_function)

    def test_with_exclusions(self):
        # Exclude specific members from testing
        self.assertDocTests(
            my_module.MyClass,
            exclude=[my_module.MyClass.internal_method]
        )

Example:

>>> import isaacsim.test.docstring
>>> tester = isaacsim.test.docstring.StandaloneDocTestCase()
>>> tester.__class__.__name__
'StandaloneDocTestCase'
Parameters:

  • *args – Additional positional arguments passed to the parent unittest.TestCase class.

  • **kwargs – Additional keyword arguments passed to the parent unittest.TestCase class.

Create an instance of the class that will use the named test method when executed. Raises a ValueError if the instance does not have a method with the specified name.

assertDocTest(
expr: object,
msg: str = '',
flags: int = 1036,
)#

Check that the examples in docstrings pass for a class/module member.

Parameters:

  • expr – Module function or class definition, property or method to check docstrings examples for.

  • msg – Custom message to display when failing.

  • flags – Doctest’s option flags.

Raises:

AssertionError – If examples in docstrings fail.

Example:

>>> from isaacsim.test.docstring import StandaloneDocTestCase
>>>
>>> tester.assertDocTest(StandaloneDocTestCase)
assertDocTests(
expr: object,
msg: str = '',
flags: int = 1036,
order: list[tuple[object, int]] = [],
exclude: list[object] = [],
stop_on_failure: bool = False,
)#

Check that the examples in docstrings pass for all class/module’s members (names).

Parameters:

  • expr – Module or class definition to check members’ docstrings examples for.

  • msg – Custom message to display when failing.

  • flags – Doctest’s option flags.

  • order – List of pair (name, index) to modify the examples execution order.

  • exclude – List of class/module names to exclude for testing.

  • stop_on_failure – Stop testing docstrings example at first encountered failure.

Raises:

AssertionError – If some docstring examples fail.

Example:

>>> from isaacsim.test.docstring import StandaloneDocTestCase
>>>
>>> tester.assertDocTests(StandaloneDocTestCase, exclude=[StandaloneDocTestCase.assertDocTests])
...