tests.context

Module Contents

Classes

BasicUsageTestSuite

Basic functional test cases.

Functions

markWithMetaTag	Decorator to apply pytest marks if pytest is available.
getCoverageCommand	Function for backend coverage command. Rather than just return the sys.executable which will usually be a python implementation, this function will search for a coverage tool to allow coverage testing to continue beyond the process fork of typical cli testing.
__check_cov_before_py	Utility Function to check for coverage availability before just using plain python. Rather than just return the sys.executable which will usually be a python implementation, this function will search for a coverage tool before falling back on just plain python.
getPythonCommand	Function for backend python command. Rather than just return the sys.executable which will usually be a python implementation, this function will search for a coverage tool with getCoverageCommand() first.
checkCovCommand	Modifies the input command arguments to include coverage-related options when applicable.
taint_command_args	Validate and sanitize command arguments for security.
validateCommandArgs	Validates command arguments to ensure they do not contain null characters.
checkStrOrByte	Converts the input to a string if possible, otherwise returns it as bytes.
checkPythonCommand	Execute a Python command and return its output.
timePythonCommand	Function for backend subprocess check_output command.
checkPythonFuzzing	Function for backend subprocess check_output command with improved error handling.
debugBlob	Helper function to debug unexpected outputs.
debugtestError	Helper function to debug unexpected outputs.
check_exec_command_has_output	Test case for command output != None.
debugUnexpectedOutput	Helper function to debug unexpected outputs.
managed_process	Context manager for safely handling multiprocessing processes.

Data

__module__
__name__
__doc__
__BLANK	A literally named variable to improve readability of code when using a blank string.

API

tests.context.__module__

‘tests’

tests.context.__name__

‘tests.context’

tests.context.__doc__ = <Multiline-String>

tests.context.__BLANK

‘str(…)’

A literally named variable to improve readability of code when using a blank string.

Meta Testing:

First set up test fixtures by importing test context.

    >>> import tests.context as _context
    >>>

Testcase 1: __BLANK should be a blank string.

    >>> import tests.context as _context
    >>> _context.__BLANK is None
    False
    >>> isinstance(_context.__BLANK, type(str()))
    True
    >>> len(_context.__BLANK) == int(0)
    True
    >>>

tests.context.markWithMetaTag(*marks: str) → callable

Decorator to apply pytest marks if pytest is available.

tests.context.getCoverageCommand() → str

Function for backend coverage command. Rather than just return the sys.executable which will usually be a python implementation, this function will search for a coverage tool to allow coverage testing to continue beyond the process fork of typical cli testing.

Meta Testing:

First set up test fixtures by importing test context.

    >>> import tests.context as _context
    >>>

Testcase 1: function should have a output.

    >>> _context.getCoverageCommand() is None
    False
    >>>

tests.context.__check_cov_before_py()

Utility Function to check for coverage availability before just using plain python. Rather than just return the sys.executable which will usually be a python implementation, this function will search for a coverage tool before falling back on just plain python.

Meta Testing:

First set up test fixtures by importing test context.

    >>> import tests.context as _context
    >>>

Testcase 1: function should have a output.

    >>> _context.__check_cov_before_py() is not None
    True
    >>>

Testcase 2: function should have a string output of python or coverage.

    >>> _test_fixture = _context.__check_cov_before_py()
    >>> isinstance(_test_fixture, type(str("")))
    True
    >>> (str("python") in _test_fixture) or (str("coverage") in _test_fixture)
    True
    >>>

tests.context.getPythonCommand() → str

Function for backend python command. Rather than just return the sys.executable which will usually be a python implementation, this function will search for a coverage tool with getCoverageCommand() first.

Meta Testing:

First set up test fixtures by importing test context.

import tests.context as _context

Testcase 1: function should have a output.

_context.getPythonCommand() is not None True

tests.context.checkCovCommand(*args)

Modifies the input command arguments to include coverage-related options when applicable.

This utility function checks if the first argument contains “coverage” and, if so, modifies the argument list to include additional coverage run options. It’s primarily used internally by other functions in the testing framework. Not intended to be run directly.

Args: *args (list): A list of command arguments; should not be pass None.

Returns: list: The modified list of arguments with ‘coverage run’ options added as applicable.

Meta Testing:

    First set up test fixtures by importing test context.

            >>> import tests.context as _context
            >>>

    Testcase 1: Function should return unmodified arguments if 'coverage' is missing.

            >>> _context.checkCovCommand("python", "script.py")
            ['python', 'script.py']

    Testcase 2: Function should modify arguments when 'coverage' is the first argument.
            A.) Missing 'run'

            >>> _context.checkCovCommand("coverage", "script.py")  #doctest: +ELLIPSIS
            ['...', 'run', '-p', '--context=Integration', '--source=multicast', 'script.py']

    Testcase 3: Function should modify arguments when 'coverage run' is in the first argument.
            A.) NOT missing 'run'

            >>> _context.checkCovCommand("coverage run", "script.py")  #doctest: +ELLIPSIS
            ['...', 'run', '-p', '--context=Integration', '--source=multicast', 'script.py']

    Testcase 4: Function should handle coverage command with full path.

            >>> _context.checkCovCommand("/usr/bin/coverage", "test.py")  #doctest: +ELLIPSIS
            ['...', 'run', '-p', '--context=Integration', '--source=multicast', 'test.py']

    Testcase 5: Function should handle coverage invoked via sys.executable.

            >>> import sys as _sys
            >>> test_fixture = [str("{} -m coverage run").format(_sys.executable), "test.py"]
            >>> _context.checkCovCommand(*test_fixture)  #doctest: +ELLIPSIS
            [..., '-m', 'coverage', 'run', '-p', '...', '--source=multicast', 'test.py']

tests.context.taint_command_args(args: list, tuple) → list

Validate and sanitize command arguments for security.

This function validates the command (first argument) against a whitelist and sanitizes all arguments to prevent command injection attacks.

Args: args (list): Command arguments to validate

Returns: list: Sanitized command arguments

Raises: CommandExecutionError: If validation fails

Meta Testing:

    >>> import tests.context as _context
    >>> import sys as _sys
    >>>

    Testcase 1: Function should validate and return unmodified Python command.

            >>> test_fixture = ['python', '-m', 'pytest']
            >>> _context.taint_command_args(test_fixture)
            ['python', '-m', 'pytest']
            >>>

    Testcase 2: Function should handle sys.executable path.

            >>> test_fixture = [str(_sys.executable), '-m', 'coverage', 'run']
            >>> result = _context.taint_command_args(test_fixture)  #doctest: +ELLIPSIS
            >>> str('python') in str(result[0]) or str('coverage') in str(result[0])
            True
            >>> result[1:] == ['-m', 'coverage', 'run']
            True
            >>>

    Testcase 3: Function should reject disallowed commands.

            >>> test_fixture = ['rm', '-rf', '/']
            >>> _context.taint_command_args(test_fixture)  #doctest: +IGNORE_EXCEPTION_DETAIL
            Traceback (most recent call last):
            multicast.exceptions.CommandExecutionError: Command 'rm' is not allowed...
            >>>

    Testcase 4: Function should validate input types.

            >>> test_fixture = None
            >>> _context.taint_command_args(test_fixture)  #doctest: +IGNORE_EXCEPTION_DETAIL
            Traceback (most recent call last):
            multicast.exceptions.CommandExecutionError: Invalid command arguments
            >>>
            >>> test_fixture = "python -m pytest"  # String instead of list
            >>> _context.taint_command_args(test_fixture)  #doctest: +IGNORE_EXCEPTION_DETAIL
            Traceback (most recent call last):
            multicast.exceptions.CommandExecutionError: Invalid command arguments
            >>>

    Testcase 5: Function should handle coverage command variations.

            >>> test_fixture = [str(_sys.executable), 'coverage', 'run', '--source=multicast']
            >>> _context.taint_command_args(test_fixture)  #doctest: +ELLIPSIS
            [...'coverage', 'run', '--source=multicast']
            >>>
            >>> test_fixture = ['coverage', 'run', '--source=multicast']
            >>> _context.taint_command_args(test_fixture)  #doctest: +ELLIPSIS
            ['exit 1 ; #', 'run',...'run', '--source=multicast']
            >>>
            >>> test_fixture = ['coverage3', 'run', '--source=.']
            >>> _context.taint_command_args(test_fixture)  #doctest: +ELLIPSIS
            ['exit 1 ; #', 'run',...'--source=.']
            >>>

    Testcase 6: Function should handle case-insensitive command validation.

            >>> test_fixture = ['Python3', '-m', 'pytest']
            >>> _context.taint_command_args(test_fixture)
            ['Python3', '-m', 'pytest']
            >>>
            >>> test_fixture = ['COVERAGE', 'run']
            >>> _context.taint_command_args(test_fixture)  #doctest: +ELLIPSIS
            [...'COVERAGE', 'run'...]
            >>>

tests.context.validateCommandArgs(args: list) → None

Validates command arguments to ensure they do not contain null characters.

Args: args (list): A list of command arguments to be validated.

Raises: ValueError: If any argument contains a null character.

tests.context.checkStrOrByte(theInput)

Converts the input to a string if possible, otherwise returns it as bytes.

This utility function is designed to handle both string and byte inputs, ensuring consistent output type. It attempts to decode byte inputs to UTF-8 strings, falling back to bytes if decoding fails.

Args: theInput: The input to be checked and potentially converted. Can be None, str, bytes, or any other type.

Returns: str: If the input is already a string or can be decoded to UTF-8. bytes: If the input is bytes and cannot be decoded to UTF-8. None: If the input is None.

Meta Testing:

    First set up test fixtures by importing test context.

            >>> import tests.context as _context
            >>>

    Testcase 1: Input is a string.

            >>> _context.checkStrOrByte("Hello")
            'Hello'
            >>>

    Testcase 2: Input is UTF-8 decodable bytes.

            >>> _context.checkStrOrByte(b"Hello")
            'Hello'
            >>>

    Testcase 3: Input is bytes that are not UTF-8 decodable.

            >>> _context.checkStrOrByte(b'\xff\xfe')
            b'ÿþ'
            >>>

    Testcase 4: Input is None.

            >>> _context.checkStrOrByte(None) is None
            True
            >>>

    Testcase 5: Input is an empty string.

            >>> _context.checkStrOrByte("")
            ''
            >>>

    Testcase 6: Input is empty bytes.

            >>> _context.checkStrOrByte(b"")
            ''
            >>>

tests.context.checkPythonCommand(args, stderr=None)

Execute a Python command and return its output.

This function is a wrapper around subprocess.check_output with additional error handling and output processing. It’s designed to execute Python commands or coverage commands, making it useful for running tests and collecting coverage data.

Args: args (list): A list of command arguments to be executed. stderr (Optional[int]): File descriptor for stderr redirection. Defaults to None.

Returns: str: The command output as a string, with any byte output decoded to UTF-8.

Raises: subprocess.CalledProcessError: If the command returns a non-zero exit status.

Meta Testing:

    First set up test fixtures by importing test context.

            >>> import sys as _sys
            >>> import tests.context as _context
            >>>

    Testcase 1: Function should have an output when provided valid arguments.

            >>> test_fixture_1 = [str(_sys.executable), '-c', 'print("Hello, World!")']
            >>> _context.checkPythonCommand(test_fixture_1)
            'Hello, World!\n'

    Testcase 2: Function should capture stderr when specified.

            >>> import subprocess as _subprocess
            >>> test_args_2 = [
            ...     str(_sys.executable), '-c', 'import sys; print("Error", file=sys.stderr)'
            ... ]
            >>>
            >>> _context.checkPythonCommand(test_args_2, stderr=_subprocess.STDOUT)
            'Error\n'

    Testcase 3: Function should handle exceptions and return output.

            >>> test_fixture_e = [str(_sys.executable), '-c', 'raise ValueError("Test error")']
            >>> _context.checkPythonCommand(
            ...     test_fixture_e, stderr=_subprocess.STDOUT
            ... ) #doctest: +ELLIPSIS
            'Traceback (most recent call last):\n...ValueError...'

    Testcase 4: Function should return the output as a string.

            >>> test_fixture_s = [str(_sys.executable), '-c', 'print(b"Bytes output")']
            >>> isinstance(_context.checkPythonCommand(
            ...     test_fixture_s, stderr=_subprocess.STDOUT
            ... ), str)
            True

tests.context.timePythonCommand(args, stderr=None)

Function for backend subprocess check_output command.

Args: args (array): An array of positional command arguments to be executed. stderr (Optional[int]): File descriptor for stderr redirection. Defaults to None.

    Returns:
            The output of checkPythonCommand.

tests.context.checkPythonFuzzing(args, stderr=None)

Function for backend subprocess check_output command with improved error handling.

Args: args (list): A list of command arguments to be executed. stderr (Optional[int]): File descriptor for stderr redirection. Defaults to None.

Returns: str: The command output as a string.

Raises: RuntimeError: If an error occurs during command execution.

Meta Testing:

    First set up test fixtures by importing test context.

            >>> import tests.context as _context
            >>>

    Testcase 1: Function should raise RuntimeError when args is None.

            >>> _context.checkPythonFuzzing(None)  #doctest: +IGNORE_EXCEPTION_DETAIL
            Traceback (most recent call last):
            multicast.exceptions.CommandExecutionError: ...

    Testcase 2: Function should raise RuntimeError when args is an empty list.

            >>> _context.checkPythonFuzzing([])  #doctest: +IGNORE_EXCEPTION_DETAIL
            Traceback (most recent call last):
            multicast.exceptions.CommandExecutionError: ...

    Testcase 3: Function should return output when valid arguments are provided.

            >>> import sys as _sys
            >>> test_fixture_3 = [str(_sys.executable), '-c', 'print("Hello, Fuzzing!")']
            >>> _context.checkPythonFuzzing(test_fixture_3)
            'Hello, Fuzzing!\n'

    Testcase 4: Function should handle coverage command and return output. Coverage will fail.

            >>> test_fixture_4 = [
            ...     'coverage run', '-c', 'print("Coverage Fuzzing!")'
            ... ]
            >>> _context.checkPythonFuzzing(test_fixture_4)  #doctest: +IGNORE_EXCEPTION_DETAIL
            Traceback (most recent call last):
            multicast.exceptions.CommandExecutionError: ...Command...
            '['coverage', 'run',...'-c'...]' returned...exit status 1...
            >>>

    Testcase 5: Function should capture stderr when specified.

            >>> import subprocess as _subprocess
            >>> test_fixture_5 = [
            ...     str(_sys.executable), '-c', 'import sys; print("Error", file=sys.stderr)'
            ... ]
            >>> _context.checkPythonFuzzing(test_fixture_5, stderr=_subprocess.STDOUT)
            'Error\n'

tests.context.debugBlob(blob=None)

Helper function to debug unexpected outputs.

Especially useful for cross-python testing where output may differ yet may be from the same logical data.

Meta Testing:

First set up test fixtures by importing test context.

    >>> import tests.context as _context
    >>>

    >>> norm_fixture = "Example Sample"
    >>> othr_fixture = """'Example Sample'"""
    >>>

Testcase 1: function should have a output.

    >>> debugBlob(norm_fixture) #doctest: -DONT_ACCEPT_BLANKLINE, +ELLIPSIS
    <BLANKLINE>
    String:
    "
    Example Sample
    "
    <BLANKLINE>
    Data:
    "
    'Example Sample'
    "
    <BLANKLINE>
    True
    >>>

Testcase 2: function should have a output even with bad input.

    >>> debugBlob(othr_fixture) #doctest: -DONT_ACCEPT_BLANKLINE, +ELLIPSIS
    <BLANKLINE>
    String:
    "
    ...Example Sample...
    "
    <BLANKLINE>
    Data:
    "
    ...'Example Sample'...
    "
    <BLANKLINE>
    True
    >>>

tests.context.debugtestError(someError)

Helper function to debug unexpected outputs.

Meta Testing:

First set up test fixtures by importing test context.

import tests.context as _context

err_fixture = RuntimeError(“Example Error”) bad_fixture = BaseException()

Testcase 1: function should have a output.

debugtestError(err_fixture) #doctest: -DONT_ACCEPT_BLANKLINE, +ELLIPSIS ERROR: <… ‘…RuntimeError’> Example Error (‘Example Error’,)

Testcase 2: function should have a output even with bad input.

debugtestError(bad_fixture) #doctest: -DONT_ACCEPT_BLANKLINE, +ELLIPSIS ERROR: <… ‘…BaseException’>

tests.context.check_exec_command_has_output(test_case, someArgs)

Test case for command output != None.

returns True if has output and False otherwise.

tests.context.debugUnexpectedOutput(expectedOutput, actualOutput, thepython)

Helper function to debug unexpected outputs.

Meta Testing:

First set up test fixtures by importing test context.

import tests.context as _context

expected_fixture = “” unexpected_fixture = “” python_fixture = “”

Testcase 1: function should have a output.

_context.debugUnexpectedOutput( … expected_fixture, unexpected_fixture, python_fixture … ) #doctest: -DONT_ACCEPT_BLANKLINE python cmd used: The expected output is… The actual output was…

Testcase 2: function should have a output even with bad input.

_context.debugUnexpectedOutput( … expected_fixture, unexpected_fixture, None … ) #doctest: -DONT_ACCEPT_BLANKLINE Warning: Unexpected output! The expected output is… The actual output was…

tests.context.managed_process(process)

Context manager for safely handling multiprocessing processes.

Ensures that the given process is properly terminated and cleaned up, even if exceptions occur during execution. This includes terminating, joining, and closing the process to prevent resource leaks.

Args: process (multiprocessing.Process): The process to manage.

Yields: multiprocessing.Process: The managed process within the context.

class tests.context.BasicUsageTestSuite(methodName='runTest')

Bases: unittest.TestCase

Basic functional test cases.

Meta Tests - Creation:

First set up test fixtures by importing test context.

import tests.context as _context

class TestCaseFixture(_context.BasicUsageTestSuite): … pass

TestCaseFixture <class ‘tests.context.TestCaseFixture’>

Testcase 1: BasicUsageTestSuite are unittest.TestCase

isinstance(BasicUsageTestSuite(“skipTest”), unittest.TestCase) True

Initialization

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.

__module__

‘tests.context’

__name__

‘tests.context.BasicUsageTestSuite’

NO_PYTHON_ERROR: str

‘No python cmd to test with!’

Error message used when Python command is not available for testing.

This constant is used across multiple test methods to maintain consistency in error reporting when Python command execution is not possible.

classmethod setUpClass() → None

Overrides unittest.TestCase.setUpClass(cls) to set up thepython test fixture.

static _always_generate_random_port_WHEN_called() → int

Generates a pseudo-random port number within the dynamic/private port range.

This method returns a random port number between 49152 and 65535, compliant with RFC 6335, suitable for temporary testing purposes to avoid port conflicts.

Returns: int: A random port number between 49152 and 65535.

setUp() → None

Overrides unittest.TestCase.setUp(unittest.TestCase). Defaults is to skip test if class is missing thepython test fixture.

_should_get_package_version_WHEN_valid() → packaging.version.Version

Retrieve the current version of the package.

This helper method imports the package and extracts the version attribute.

Returns: packaging.version.Version – A validated version object from the version attribute. Raises: AssertionError – If the version string is invalid or cannot be retrieved. ImportError – If the multicast package cannot be imported.

test_absolute_truth_and_meaning() → None

Test case 0: Insanity Test.

test_finds_python_WHEN_testing() → None

Test case 1: Class Test-Fixture Meta Test.

tearDown() → None

Overrides unittest.TestCase.tearDown(unittest.TestCase). Defaults is to reset the random port test fixture.

classmethod tearDownClass() → None

Overrides unittest.TestCase.tearDownClass(cls) to clean up thepython test fixture.