Class Session

tests/debug/session.py:28–1020

A test debug session. Manages the lifetime of the adapter and the debuggee processes, captures debuggee stdio output, establishes a DAP message channel to the debuggee, and records all DAP messages in that channel on a Timeline object. Must be used in a with-statement for proper cleanup

class Session(object):
    """A test debug session. Manages the lifetime of the adapter and the debuggee
    processes, captures debuggee stdio output, establishes a DAP message channel to
    the debuggee, and records all DAP messages in that channel on a Timeline object.

    Must be used in a with-statement for proper cleanup. On successful exit - if no
    exception escapes from the with-statement - the session will:

    1. Invoke wait_for_exit(), unless expected_exit_code is None.
    2. Invoke disconnect().
    3. Wait for the adapter process to exit.
    4. Finalize and closes the timeline

    If the exit is due to an exception, the session will:

    1. Invoke disconnect(force=True).
    2. Kill the debuggee and the adapter processes.

    Example::

        with debug.Session() as session:
            # Neither debuggee nor adapter are spawned yet. Initial configuration.
            session.log_dir = ...
            session.config.update({...})

            with session.launch(...):
                # Debuggee and adapter are spawned, but there is no code executing
                # in the debuggee yet.
                session.set_breakpoints(...)

            # Code is executing in the debuggee.
            session.wait_for_stop(expected_frames=[...])
            assert session.get_variable(...) == ...
            session.request_continue()

        # Session is disconnected from the debuggee, and both the debuggee and the
        # adapter processes have exited.
        assert session.exit_code == ...
    """

    tmpdir = None
    """Temporary directory in which Sessions can create the temp files they need.

    Automatically set to tmpdir for the current test by pytest_fixtures.test_wrapper().
    """

    @classmethod
    def reset_counter(cls):
        cls._counter = itertools.count(1)

    def __init__(self, debug_config=None):
        assert Session.tmpdir is not None
        watchdog.start()

        self.id = next(Session._counter)
        log.info("Starting {0}", self)

        self.client_id = "vscode"