[isaacsim.test.docstring] Isaac Sim DocTest#

Version: 1.3.1

Overview#

The isaacsim.test.docstring extension provides test case base classes for validating Python docstring examples using Python’s doctest module. It enables developers to automatically test code examples within docstrings to ensure they execute correctly and produce expected outputs, supporting both standalone unittest environments and Kit’s async testing framework.

Key Components#

`StandaloneDocTestCase`#

StandaloneDocTestCase serves as the base class for standalone test cases that validate docstring examples outside of Kit environments. This class extends Python’s unittest.TestCase and provides specialized methods for docstring testing in traditional Python testing scenarios.

The class offers two primary testing methods:

assertDocTest() - Tests docstring examples for a single class, module member, or function
assertDocTests() - Tests docstring examples for all members within a module or class

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)

`AsyncDocTestCase`#

AsyncDocTestCase extends omni.kit.test.AsyncTestCase to provide docstring testing capabilities within Kit’s async testing environment. This class is specifically designed for testing extension modules and async code examples that require Kit’s application context.

The async version includes an additional await_update parameter that allows Kit application updates between docstring tests, ensuring proper execution timing in async environments.

from isaacsim.test.docstring import AsyncDocTestCase
import my_extension_module

class TestDocstrings(AsyncDocTestCase):
    async def test_my_module_docstrings(self):
        await self.assertDocTests(my_extension_module)

    async def test_with_options(self):
        await self.assertDocTests(
            my_extension_module.MyClass,
            exclude=[my_extension_module.MyClass.internal_method],
            await_update=True
        )

Functionality#

Doctest Directive Support#

Both test case classes support standard doctest directives that control test execution behavior:

# doctest: +NO_CHECK - Runs the example but skips output verification
# doctest: +SKIP - Completely skips the example during testing
# doctest: +ELLIPSIS - Allows ... in expected output to match any substring
# doctest: +NORMALIZE_WHITESPACE - Ignores whitespace differences in output comparison

Test Customization#

The extension provides several options for customizing docstring test execution:

Exclusion filtering - Skip specific members from testing using the exclude parameter
Execution ordering - Control the order of test execution with the order parameter
Failure handling - Use stop_on_failure to halt testing at the first encountered failure
Custom messaging - Provide custom assertion messages for failed tests

Integration#

Uses omni.kit.test to provide async testing capabilities within Kit environments, allowing docstring tests to properly interact with Kit’s application lifecycle and async execution model.

Enable Extension#

The extension can be enabled (if not already) in one of the following ways:

Command-line interface

Define the next entry as an application argument from a terminal.

APP_SCRIPT.(sh|bat) --enable isaacsim.test.docstring

Experience/extension configuration

Define the next entry under [dependencies] in an experience (.kit) file or an extension configuration (extension.toml) file.

[dependencies]
"isaacsim.test.docstring" = {}

Extension Manager UI

Open the Window > Extensions menu in a running application instance and search for isaacsim.test.docstring. Then, toggle the enable control button if it is not already active.

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, ) → None#

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]] | None = None, exclude: list[object] | None = None, stop_on_failure: bool = False, await_update: bool = True, ) → None#

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: object, **kwargs: object)#

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, ) → None#

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]] | None = None, exclude: list[object] | None = None, stop_on_failure: bool = False, ) → None#

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])
... 

Python API

[isaacsim.test.docstring] Isaac Sim DocTest#

Overview#

Key Components#

StandaloneDocTestCase#

AsyncDocTestCase#

Functionality#

Doctest Directive Support#

Test Customization#

Integration#

Enable Extension#

Python API#

Test Cases#

`StandaloneDocTestCase`#

`AsyncDocTestCase`#