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

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

@@ -1,3 +1,10 @@
+## 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.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: esp-test-utils
-Version: 0.2.2
+Version: 0.2.3
 Summary: ESP Test Utils
 Author-email: Chen Yudong <chenyudong@espressif.com>
 License:                              Apache License

{esp_test_utils-0.2.2 → esp_test_utils-0.2.3}/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.2.3
 Summary: ESP Test Utils
 Author-email: Chen Yudong <chenyudong@espressif.com>
 License:                              Apache License

{esp_test_utils-0.2.2 → esp_test_utils-0.2.3}/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
@@ -84,10 +85,11 @@ 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

{esp_test_utils-0.2.2 → esp_test_utils-0.2.3}/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.2.3}/esptest/adapter/port/base_port.py

@@ -31,9 +31,12 @@ 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 +246,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 +366,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 +388,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
 
@@ -486,9 +493,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 +510,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.2.3/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.2.3}/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}')

esp_test_utils-0.2.3/tests/adapter/test_shell_port.py

@@ -0,0 +1,94 @@
+import random
+import re
+import subprocess
+import time
+from pathlib import Path
+
+import pytest
+
+from esptest.adapter.port.shell_port import PexpectPort, ShellPort, ShellRaw
+
+
+def test_shell_raw_open_close() -> None:
+    ran_int = random.randint(12345678, 87654321)
+    raw_port = ShellRaw(cmd=f'sleep {ran_int}')
+    assert raw_port.proc is not None
+    output = subprocess.check_output(f'ps -ef | grep {ran_int}', shell=True).decode('utf-8')
+    assert f'sleep {ran_int}' in output
+    raw_port.close()
+    output = subprocess.check_output(f'ps -ef | grep {ran_int}', shell=True).decode('utf-8')
+    assert f'sleep {ran_int}' not in output
+
+
+def test_shell_port_open_close() -> None:
+    ran_int = random.randint(12345678, 87654321)
+    # close by close method
+    port = ShellPort(cmd=f'sleep {ran_int}')
+    assert isinstance(port.raw_port, ShellRaw)
+    output = subprocess.check_output(f'ps -ef | grep {ran_int}', shell=True).decode('utf-8')
+    assert f'sleep {ran_int}' in output
+    port.close()
+    output = subprocess.check_output(f'ps -ef | grep {ran_int}', shell=True).decode('utf-8')
+    assert f'sleep {ran_int}' not in output
+    # close by with statement
+    with ShellPort(cmd=f'sleep {ran_int}') as port:
+        assert isinstance(port.raw_port, ShellRaw)
+        output = subprocess.check_output(f'ps -ef | grep {ran_int}', shell=True).decode('utf-8')
+        assert f'sleep {ran_int}' in output
+    output = subprocess.check_output(f'ps -ef | grep {ran_int}', shell=True).decode('utf-8')
+    assert f'sleep {ran_int}' not in output
+
+
+def test_shell_port_read_write() -> None:
+    with ShellPort(cmd='/bin/bash') as port:
+        port.write_line('echo hello')
+        time.sleep(0.1)  # wait for the receive thread
+        assert 'hello' in port.read_all_data()
+        port.write_line('sleep 0.1 && echo world')
+        assert 'world' not in port.read_all_data()
+        match = port.expect(re.compile('world'))
+        assert match.group(0) == 'world'
+
+
+def test_shell_port_logfile(tmp_path: Path) -> None:
+    log_file = tmp_path / 'shell_port1.log'
+    with ShellPort(cmd='/bin/bash', log_file=str(log_file)) as port:
+        port.write_line('echo hello')
+        time.sleep(0.1)  # wait for the receive thread
+        with open(str(log_file), 'r') as f:
+            assert 'hello' in f.read()
+        port.log_file = str(tmp_path / 'shell_port2.log')
+        port.write_line('echo world')
+        time.sleep(0.1)  # wait for the receive thread
+        with open(str(tmp_path / 'shell_port2.log'), 'r') as f:
+            assert 'world' in f.read()
+
+
+def test_pexpect_spawn_port_read_write() -> None:
+    with PexpectPort(cmd='/bin/bash') as port:
+        port.write_line('echo hello')
+        time.sleep(0.5)  # wait for the receive thread
+        assert 'hello' in port.read_all_data()
+        port.write_line('sleep 0.1 && echo world')
+        assert 'world' not in port.read_all_data()
+        match = port.expect(re.compile('world'))
+        assert match.group(0) == 'world'
+
+
+def test_pexpect_spawn_port_logfile(tmp_path: Path) -> None:
+    log_file = tmp_path / 'shell_port1.log'
+    with PexpectPort(cmd='/bin/bash', log_file=str(log_file)) as port:
+        port.write_line('echo hello')
+        time.sleep(0.5)  # wait for the receive thread
+        with open(str(log_file), 'r') as f:
+            assert 'hello' in f.read()
+        port.log_file = str(tmp_path / 'shell_port2.log')
+        port.write_line('echo world')
+        time.sleep(0.1)  # wait for the receive thread
+        with open(str(tmp_path / 'shell_port2.log'), 'r') as f:
+            assert 'world' in f.read()
+
+
+if __name__ == '__main__':
+    # Breakpoints do not work with coverage, disable coverage for debugging
+    pytest.main([__file__, '--no-cov', '--log-cli-level=DEBUG'])

{esp_test_utils-0.2.2 → esp_test_utils-0.2.3}/tests/test_EnvConfig.py

@@ -65,6 +65,30 @@ def test_env_config_get_var(tmp_path: Path) -> None:
             env_config.get_variable('dut_port')
 
 
+def test_env_config_from_shell_env(tmp_path: Path) -> None:
+    # Test Get variable from console
+    config_file = tmp_path / 'not_exist_config.yml'
+    env = {
+        'TEST_ENV_CONFIG_FILE': str(config_file),
+    }
+    with reload_envconfig(env):
+        try:
+            os.environ.pop('RUNNER_WIFI_SSID')
+        except KeyError:
+            pass
+        try:
+            os.environ.pop('RUNNER_AP_SSID')
+        except KeyError:
+            pass
+        env_config = EnvConfig()
+        env_config.ALLOW_INPUT = False
+        with pytest.raises(ValueError):
+            var = env_config.get_variable('ap_ssid')
+        os.environ['RUNNER_AP_SSID'] = 'ssid_from_env'
+        var = env_config.get_variable('ap_ssid')
+        assert var == 'ssid_from_env'
+
+
 def test_env_config_from_console(tmp_path, monkeypatch):  # type: ignore
     # Test Get variable from console
     config_file = tmp_path / 'not_exist_config.yml'