esp-test-utils 0.2.2__tar.gz → 0.3.0__tar.gz

{esp_test_utils-0.2.2 → esp_test_utils-0.3.0}/CHANGELOG.md

@@ -1,3 +1,19 @@
+## v0.3.0 (2025-12-10)
+
+
+- feat: esp-listports support monitor mode
+- feat: add more logs to H3CSwitch
+- feat: esp-downbin support argument --force-no-stub
+- feat: add h3c switch device control
+- feat: add decorator timeit
+
+## v0.2.3 (2025-11-14)
+
+
+- feat: add shell port support
+- fix: Fix esptool connect to given port
+- fix: log of env config search dirs
+
 ## v0.2.2 (2025-10-29)
 
 

{esp_test_utils-0.2.2 → esp_test_utils-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: esp-test-utils
-Version: 0.2.2
+Version: 0.3.0
 Summary: ESP Test Utils
 Author-email: Chen Yudong <chenyudong@espressif.com>
 License:                              Apache License
@@ -228,8 +228,10 @@ Requires-Dist: pyserial
 Requires-Dist: PyYAML
 Requires-Dist: pexpect
 Requires-Dist: pyusb
+Requires-Dist: pyudev
 Requires-Dist: esptool
 Requires-Dist: packaging
+Requires-Dist: rich
 Requires-Dist: sqlalchemy
 Requires-Dist: typing_extensions; python_version < "3.11"
 Provides-Extra: idfci

{esp_test_utils-0.2.2 → esp_test_utils-0.3.0}/esp_test_utils.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: esp-test-utils
-Version: 0.2.2
+Version: 0.3.0
 Summary: ESP Test Utils
 Author-email: Chen Yudong <chenyudong@espressif.com>
 License:                              Apache License
@@ -228,8 +228,10 @@ Requires-Dist: pyserial
 Requires-Dist: PyYAML
 Requires-Dist: pexpect
 Requires-Dist: pyusb
+Requires-Dist: pyudev
 Requires-Dist: esptool
 Requires-Dist: packaging
+Requires-Dist: rich
 Requires-Dist: sqlalchemy
 Requires-Dist: typing_extensions; python_version < "3.11"
 Provides-Extra: idfci

{esp_test_utils-0.2.2 → esp_test_utils-0.3.0}/esp_test_utils.egg-info/SOURCES.txt

@@ -33,6 +33,7 @@ esptest/adapter/dut/wrapper.py
 esptest/adapter/port/__init__.py
 esptest/adapter/port/base_port.py
 esptest/adapter/port/serial_port.py
+esptest/adapter/port/shell_port.py
 esptest/common/__init__.py
 esptest/common/compat_typing.py
 esptest/common/data_monitor.py
@@ -51,6 +52,7 @@ esptest/devices/attenuator.py
 esptest/devices/esp_serial.py
 esptest/devices/serial_dut.py
 esptest/devices/serial_tools.py
+esptest/devices/switch.py
 esptest/env/__init__.py
 esptest/env/base_env.py
 esptest/env/wifi_env.py
@@ -78,19 +80,22 @@ esptest/tools/copy_bin.py
 esptest/tools/download_bin.py
 esptest/tools/http_download.py
 esptest/tools/pip_check.py
+esptest/tools/uart_monitor.py
 esptest/utility/gen_esp32part.py
 esptest/utility/parse_bin_path.py
 example/jap_test.py
 example/restart_test.py
 tests/__init__.py
 tests/conftest.py
-tests/test_Dut.py
 tests/test_EnvConfig.py
 tests/test_common.py
 tests/test_import.py
+tests/adapter/test_Dut.py
+tests/adapter/test_shell_port.py
 tests/basic/test_decorators.py
 tests/basic/test_network.py
 tests/db/test_db_runners.py
+tests/devices/test_switch.py
 tests/esp_console/conftest.py
 tests/esp_console/test_WifiCmd.py
 tests/esp_console/_files/wifi_cmd_connected_1.log

{esp_test_utils-0.2.2 → esp_test_utils-0.3.0}/esp_test_utils.egg-info/requires.txt

@@ -3,8 +3,10 @@ pyserial
 PyYAML
 pexpect
 pyusb
+pyudev
 esptool
 packaging
+rich
 sqlalchemy
 
 [:python_version < "3.11"]

{esp_test_utils-0.2.2 → esp_test_utils-0.3.0}/esptest/adapter/dut/esp_mixin.py

@@ -51,15 +51,17 @@ class EspSerial:
 
 class EspMixin(BaseProtocol):
     def _esptool_open_port(self, port: str, initial_baud: int, **kwargs: t.Any) -> esptool.ESPLoader:
-        ports = [p.device for p in get_all_serial_ports()]
         port = compute_serial_port(port) if port else ''
+        serial_list = [port] if port else [p.device for p in get_all_serial_ports()]
+        # esptool.get_default_connected_device always detect_chip from serial_list
         esp = esptool.get_default_connected_device(
-            ports,
-            port,
+            serial_list,
+            port=port or None,  # type: ignore
             connect_attempts=3,
             initial_baud=initial_baud,
             chip=kwargs.get('chip', 'auto'),
         )
+        assert esp, f'Failed to connect to {port}'
         return esp
 
     def _esptool_path(self, use_esptool: str = '') -> str:

{esp_test_utils-0.2.2 → esp_test_utils-0.3.0}/esptest/adapter/port/base_port.py

@@ -26,14 +26,24 @@ NEVER_MATCHED_MAGIC_STRING = 'o6K,Q.(w+~yr~N9R'
 class ExpectTimeout(TimeoutError):
     """raise same ExpectTimeout rather than different Exception from different framework"""
 
+    def __init__(self, message: str, data_in_buffer: t.Union[str, bytes] = b'') -> None:
+        super().__init__(message)
+        self.data_in_buffer: t.Union[str, bytes] = data_in_buffer
+
+    def __str__(self) -> str:
+        return f'{super().__str__()}\n data_in_buffer={repr(self.data_in_buffer)}'
+
 
 class RawPort(metaclass=abc.ABCMeta):
     """Define a minimum Dut class, the dut objects should at least support these methods
 
     the dut should at least support these attributes:
-    - attribute name with type str
     - method: write_bytes() with parameters: data[bytes]
     - method: read_bytes() with parameters: timeout[float]
+
+    optional attribute & method:
+    - attribute: name with type str
+    - attribute: read_timeout with type float
     """
 
     @classmethod
@@ -243,7 +253,11 @@ class PortSpawn(pexpect.spawnbase.SpawnBase, t.Generic[T]):
         self._log(ret_data, 'read')  # type: ignore
         return ret_data
 
+    @deprecated('Should use close() for Spawn')
     def stop(self) -> None:
+        self.close()
+
+    def close(self) -> None:
         """Stop and clean up"""
         self.logger.debug(f'Stopping SerialSpawn {self.name}')
         self._read_thread_stop_event.set()
@@ -359,7 +373,7 @@ class BasePort(PortInterface, t.Generic[T]):
         if new_log_file == self._log_file:
             return
         if self._pexpect_spawn:
-            self._pexpect_spawn.serial_log_file = new_log_file
+            self._pexpect_spawn.log_file = new_log_file
         self._log_file = new_log_file
 
     @property
@@ -381,7 +395,7 @@ class BasePort(PortInterface, t.Generic[T]):
         if not self._pexpect_spawn:
             return False
         self._init_log_file()
-        self._pexpect_spawn.stop()
+        self._pexpect_spawn.close()
         self._pexpect_spawn = None
         return True
 
@@ -401,7 +415,12 @@ class BasePort(PortInterface, t.Generic[T]):
             try:
                 result = func(self, *args, **kwargs)
             except self.expect_timeout_exceptions as e:
-                raise ExpectTimeout(str(e)) from e
+                try:
+                    data_in_buffer = self._pexpect_spawn.before  # pylint: disable=protected-access
+                except AttributeError:
+                    data_in_buffer = ''
+                self.logger.debug(f'ExpectTimeout: {str(e)}, data_in_buffer={repr(data_in_buffer)}')
+                raise ExpectTimeout(str(e), data_in_buffer=data_in_buffer) from e
             return result
 
         return wrap
@@ -486,9 +505,13 @@ class BasePort(PortInterface, t.Generic[T]):
         """
         buffer = b''
         if flush:
-            match = self.expect(re.compile(b'.*', re.DOTALL), timeout=0)
-            assert match
-            buffer = match.group(0)
+            # pexpect may return empty bytes if b'(.*)' is used
+            try:
+                match = self.expect(re.compile(b'(.+)', re.DOTALL), timeout=0)
+                assert match
+                buffer = match.group(0)
+            except TimeoutError:
+                pass
         else:
             # flush spawn buffer
             assert self._pexpect_spawn
@@ -499,7 +522,11 @@ class BasePort(PortInterface, t.Generic[T]):
 
     def close(self) -> None:
         if self._close_redirect_thread_when_exit and self._pexpect_spawn:
-            self._pexpect_spawn.stop()
+            self._pexpect_spawn.close()
+        if self.raw_port:
+            if hasattr(self.raw_port, 'close'):
+                assert callable(self.raw_port.close)  # type: ignore
+                self.raw_port.close()  # type: ignore
 
     def __enter__(self) -> 't.Self':
         return self

esp_test_utils-0.3.0/esptest/adapter/port/shell_port.py

@@ -0,0 +1,191 @@
+import os
+import subprocess
+import time
+
+import pexpect
+import psutil
+
+import esptest.common.compat_typing as t
+
+from ...logger import get_logger
+from .base_port import BasePort, RawPort
+
+logger = get_logger('shell_port')
+
+
+class ShellRaw(RawPort):
+    """A subprocess Raw Port class that supports shell read, write
+
+    is a subclass of RawPort
+    """
+
+    def __init__(self, cmd: str = '/bin/bash', env: t.Optional[t.Dict[str, str]] = None) -> None:
+        self.env = env or os.environ.copy()
+        self.env['PYTHONUNBUFFERED'] = 'true'  # for python scripts, disable output buffering
+        self.cmd = cmd
+        self.proc: t.Optional[subprocess.Popen] = None
+        self.read_timeout = 0.002  # default read_timeout
+        self.open()
+
+    def open(self) -> None:
+        if not self.proc:
+            self.proc = subprocess.Popen(  # pylint: disable=consider-using-with
+                self.cmd,
+                shell=True,
+                env=self.env,
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+            )
+            # Set stdout to non-blocking
+            os.set_blocking(self.proc.stdout.fileno(), False)  # type: ignore
+
+    def close(self) -> None:
+        """Close subprocess."""
+        if self.proc:
+            if self.proc.pid:
+                try:
+                    proc = psutil.Process(self.proc.pid)
+                    for child in proc.children(recursive=True):
+                        child.kill()
+                    proc.kill()
+                    time.sleep(0.01)
+                except psutil.Error:
+                    pass
+                # # Unix / Linux - does not work
+                # try:
+                #     os.killpg(self.proc.pid, signal.SIGTERM)  # send SIGTERM to all in the group
+                #     os.killpg(self.proc.pid, signal.SIGKILL)  # send SIGTERM to all in the group
+                # except ProcessLookupError:
+                #     pass
+            self.proc.terminate()
+            self.proc.kill()
+            self.proc.wait()
+            logger.info(f'shell command [{self.cmd}] was killed')
+        self.proc = None
+
+    def write_bytes(self, data: bytes) -> None:
+        """Write bytes to subprocess stdin."""
+        if self.proc:
+            self.proc.stdin.write(data)  # type: ignore
+            self.proc.stdin.flush()  # type: ignore
+            return
+        raise ValueError('Subprocess not initialized.')
+
+    def read_bytes(self, timeout: float = 0) -> bytes:
+        """blocking read bytes"""
+        data = self.read_bytes_nonblocking()
+        if not data and timeout > 0:
+            time.sleep(timeout)  # blocking read
+            data = self.read_bytes_nonblocking()
+        if data:
+            logger.debug(f'[{self.cmd}] read_bytes timeout={timeout}, data={str(data)}')
+        return data
+
+    def read_bytes_nonblocking(self, size: int = -1) -> bytes:
+        """non-blocking read bytes"""
+        if self.proc:
+            self.proc.stdout.flush()  # type: ignore
+            return self.proc.stdout.read(size)  # type: ignore
+        return b''
+
+
+class ShellPort(BasePort[ShellRaw]):
+    """A combined port class that supports shell read, write, expect"""
+
+    def __init__(
+        self,
+        cmd: str = '/bin/bash',
+        env: t.Optional[dict[str, str]] = None,
+        name: str = '',
+        log_file: str = '',
+        **kwargs: t.Any,
+    ) -> None:
+        raw_port = ShellRaw(cmd=cmd, env=env)
+        super().__init__(raw_port, name, log_file, **kwargs)
+
+
+class InvalidRaw(RawPort):
+    """A invalid Raw Port class that always raise NotImplementedError to pass type check"""
+
+    def write_bytes(self, data: bytes) -> None:
+        """Write bytes to subprocess stdin."""
+        raise NotImplementedError('Invalid Raw Port.')
+
+    def read_bytes(self, timeout: float = 0) -> bytes:
+        """blocking read bytes"""
+        raise NotImplementedError('Invalid Raw Port.')
+
+
+class PexpectPort(BasePort[InvalidRaw]):
+    """A pexpect Port class that supports shell read, write, expect
+
+    based on pexpect.spawn but use different expect method
+    """
+
+    def __init__(
+        self,
+        cmd: str = '/bin/bash',
+        name: str = '',
+        log_file: str = '',
+        **kwargs: t.Any,
+    ) -> None:
+        self._cmd = cmd
+        raw_port = InvalidRaw()
+        self._pexpect_spawn: t.Optional[pexpect.spawn] = None  # change type
+        self.log_file_f = open(log_file, 'wb') if log_file else None  # pylint: disable=consider-using-with
+        super().__init__(raw_port, name, log_file, **kwargs)
+
+    @property
+    def log_file(self) -> str:
+        """Get Current dut log file."""
+        if not self._log_file:
+            return ''
+        return os.path.abspath(self._log_file)
+
+    @log_file.setter
+    def log_file(self, new_log_file: str) -> None:
+        """Set Current dut log file."""
+        if new_log_file == self._log_file:
+            return
+        if self.log_file_f:
+            if self._pexpect_spawn:
+                self._pexpect_spawn.logfile = None  # type: ignore
+            self.log_file_f.close()
+        if self._pexpect_spawn:
+            self.log_file_f = open(new_log_file, 'wb') if new_log_file else None  # pylint: disable=consider-using-with
+            self._pexpect_spawn.logfile = self.log_file_f  # type: ignore
+        self._log_file = new_log_file
+
+    @property
+    def spawn(self) -> t.Optional[pexpect.spawn]:  # type: ignore
+        """Allow the use of pexpect spawn enhancements, if pexpect process is available"""
+        return self._pexpect_spawn
+
+    def start_redirect_thread(self) -> None:
+        """Start a new thread to read data from port and save to data cache."""
+        if self._pexpect_spawn:
+            return
+        self._init_log_file()
+        env = os.environ.copy()
+        env['PYTHONUNBUFFERED'] = 'true'  # for python scripts, disable output buffering
+        self._pexpect_spawn = pexpect.spawn(self._cmd, maxread=8192, echo=False, env=env)  # type: ignore
+        self._pexpect_spawn.logfile = self.log_file_f  # type: ignore
+        # self._pexpect_spawn.delaybeforesend = 0.001
+
+    def stop_redirect_thread(self) -> bool:
+        """Stop the redirect thread and pexpect process."""
+        if not self._pexpect_spawn:
+            return False
+        self._init_log_file()
+        self._pexpect_spawn.close()
+        self._pexpect_spawn = None  # type: ignore
+        return True
+
+    def close(self) -> None:
+        """Close pexpect process."""
+        super().close()
+        self.stop_redirect_thread()
+        if self.log_file_f:
+            self.log_file_f.close()
+            self.log_file_f = None

{esp_test_utils-0.2.2 → esp_test_utils-0.3.0}/esptest/common/decorators.py

@@ -109,3 +109,23 @@ def suppress_stdout() -> t.Callable[[GenericFunc], GenericFunc]:
         return t.cast(GenericFunc, wrapper)
 
     return decorator
+
+
+def timeit(
+    print_func: t.Callable[[str], None] = logger.critical,
+    format_str: str = 'Func {func_name} time used: {time_used:.2f} s',
+) -> t.Callable[[GenericFunc], GenericFunc]:
+    """Show time used when method is called"""
+
+    def decorator(func: GenericFunc) -> GenericFunc:
+        @wraps(func)
+        def wrapper(*args: t.Any, **kwargs: t.Any) -> t.Any:
+            start_time = time.perf_counter()
+            ret = func(*args, **kwargs)
+            end_time = time.perf_counter()
+            print_func(format_str.format(func_name=func.__name__, time_used=end_time - start_time))
+            return ret
+
+        return t.cast(GenericFunc, wrapper)
+
+    return decorator

{esp_test_utils-0.2.2 → esp_test_utils-0.3.0}/esptest/config/env_config.py

@@ -113,10 +113,7 @@ class EnvConfig:
                 continue
             config_file = os.path.join(_dir, cls.ENV_CONFIG_FILE_BASE_NAME)
         if not config_file:
-            _msg = (
-                'Can not find env config file from:\n  ',
-                '  \n'.join(cls._search_dirs()),
-            )
+            _msg = 'Can not find env config file from:\n  ' + '  \n'.join(cls._search_dirs())
             logging.warning(_msg)
             if not cls.ALLOW_INPUT:
                 raise FileNotFoundError(f'Could not find config file: {cls.ENV_CONFIG_FILE_BASE_NAME}')