esp-test-utils 0.3.1__tar.gz → 0.3.2__tar.gz

{esp_test_utils-0.3.1 → esp_test_utils-0.3.2}/CHANGELOG.md

@@ -1,3 +1,11 @@
+## v0.3.2 (2026-03-19)
+
+
+- feat: add downbin with configs
+- feat: add secure boot match check
+- fix: parse partition for read-only dir
+- change: add debug logs for downbin
+
 ## v0.3.1 (2026-01-16)
 
 

{esp_test_utils-0.3.1 → esp_test_utils-0.3.2}/PKG-INFO

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

{esp_test_utils-0.3.1 → esp_test_utils-0.3.2}/docs/conf.py

@@ -20,6 +20,9 @@ extensions = [
     'sphinx.ext.napoleon',
 ]
 
+# Use type hints from signature in parameter descriptions (avoids duplicating complex types in docstrings)
+autodoc_typehints = 'description'
+
 templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 

{esp_test_utils-0.3.1 → esp_test_utils-0.3.2}/esp_test_utils.egg-info/PKG-INFO

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

{esp_test_utils-0.3.1 → esp_test_utils-0.3.2}/esp_test_utils.egg-info/SOURCES.txt

@@ -107,6 +107,7 @@ tests/iperf_utility/_files/dut_iperf_rx1.log
 tests/iperf_utility/_files/dut_iperf_rx2.log
 tests/iperf_utility/_files/pc_iperf_rx.log
 tests/iperf_utility/_files/pc_iperf_rx2.log
+tests/tools/test_download_bin.py
 tests/tools/test_download_file.py
 tests/tools/test_pip_check.py
 tests/utility/test_parse_bin_path.py

{esp_test_utils-0.3.1 → esp_test_utils-0.3.2}/esptest/common/decorators.py

@@ -16,6 +16,18 @@ GenericFunc = t.TypeVar('GenericFunc', bound=t.Callable[..., t.Any])
 
 
 def enhance_import_error_message(message: str) -> t.Callable[[GenericFunc], GenericFunc]:
+    """Decorator that enriches ImportError with function name and custom message.
+
+    When the decorated function raises an ImportError, the exception message
+    is appended with `` from {func.__name__}: {message}`` to aid fixing.
+
+    Args:
+        message (str): Extra hint to append to the ImportError message.
+
+    Returns:
+        t.Callable[[GenericFunc], GenericFunc]: A decorator for the target function.
+    """
+
     def decorator(func: GenericFunc) -> GenericFunc:
         @wraps(func)
         def wrapper(*args: t.Any, **kwargs: t.Any) -> t.Any:
@@ -42,17 +54,26 @@ def retry(
 ) -> t.Callable[[GenericFunc], GenericFunc]:
     """Retry decorator
 
-    For parameter "on_result", it can be a list or a callable.
+    The decorated function is called at most ``max_retry`` times. A retry happens when:
+    - The return value fails the ``on_result`` check (if configured), or
+    - An exception matching ``on_exception`` is raised (if configured).
 
+    **on_result** controls retry based on return value. It can be:
+    - **list**: Retry when the return value is **not** in the list; stop and return when it is in the list.
+    - **callable**: Retry when the callable returns True (result unacceptable); stop and return when it returns False.
+    Default is a callable that always returns False, so no retry based on result.
+
+    **on_exception** limits which exceptions trigger a retry. Only exceptions whose type is in this tuple
+    are caught and cause a retry; others are re-raised. Default uses an internal sentinel so no retry on exception.
 
     Args:
-        max_retry (int, optional): Max retry count. Defaults to 3.
-        on_result (Union[List[t.Any], Callable[[Any], bool]], optional): Retry if the result if not expected.
-        on_exception (Tuple[Type[Exception], ...], optional): Retry if exception, do not handle exception by default.
-        delay (float, optional): Delay before next retry. Defaults to 0.
+        max_retry: Maximum number of total calls. Defaults to 3.
+        on_result: Retry based on return value, see description above. Default: no retry on result.
+        on_exception: Retry when one of these exceptions is raised. Default: no exception handled.
+        delay: Delay before next retry. Defaults to 0.
 
     Returns:
-        t.Callable[[GenericFunc], GenericFunc]: decorator
+        t.Callable[[GenericFunc], GenericFunc]: A decorator for the target function.
     """
 
     def decorator(func: GenericFunc) -> GenericFunc:
@@ -98,12 +119,13 @@ def deprecated(reason: str = '') -> t.Callable[[GenericFunc], GenericFunc]:
 
 
 def suppress_stdout() -> t.Callable[[GenericFunc], GenericFunc]:
-    """Disable all stdout and stderr"""
+    """Redirect stdout and stderr to discard output during the decorated function's execution."""
 
     def decorator(func: GenericFunc) -> GenericFunc:
         @wraps(func)
         def wrapper(*args: t.Any, **kwargs: t.Any) -> t.Any:
-            with contextlib.redirect_stdout(io.StringIO()):
+            devnull = io.StringIO()
+            with contextlib.redirect_stdout(devnull), contextlib.redirect_stderr(devnull):
                 return func(*args, **kwargs)
 
         return t.cast(GenericFunc, wrapper)
@@ -115,7 +137,18 @@ 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"""
+    """Show time used after method is called.
+
+    After the function returns, ``print_func`` is called with the formatted string
+    (supports ``{func_name}`` and ``{time_used}`` placeholders).
+
+    Args:
+        print_func callable[[str], None]: Callable to output the timing message. Defaults to logger.critical.
+        format_str str: Format string for the message. Defaults to 'Func {func_name} time used: {time_used:.2f} s'.
+
+    Returns:
+        t.Callable[[GenericFunc], GenericFunc]: A decorator for the target function.
+    """
 
     def decorator(func: GenericFunc) -> GenericFunc:
         @wraps(func)

{esp_test_utils-0.3.1 → esp_test_utils-0.3.2}/esptest/scripts/downbin.py

@@ -29,7 +29,8 @@ def main() -> None:
 
     log_level = [logging.WARNING, logging.INFO, logging.DEBUG]
     logging.basicConfig(
-        level=log_level[min(args.verbose, len(log_level) - 1)], format='%(asctime)s %(levelname)s %(message)s'
+        level=log_level[min(args.verbose, len(log_level) - 1)],
+        format='%(asctime)s %(levelname)s %(module)s :: %(message)s',
     )
 
     bin_path = args.bin_path or './build'

{esp_test_utils-0.3.1 → esp_test_utils-0.3.2}/esptest/tools/download_bin.py

@@ -8,6 +8,7 @@ import sys
 import tempfile
 import zipfile
 from asyncio.events import AbstractEventLoop
+from dataclasses import dataclass
 from functools import lru_cache, partial
 
 from esptool import get_default_connected_device
@@ -19,6 +20,8 @@ from esptest.tools.http_download import download_file
 from esptest.utility.parse_bin_path import ParseBinPath
 
 logger = get_logger('download_bin')
+FLASH_CRYPT_CNT_PATTERN = re.compile(r'(?:FLASH_CRYPT_CNT|SPI_BOOT_CRYPT_CNT).*\(0b([01]+)')
+SECURE_BOOT_EN_PATTERN = re.compile(r'(?:ABS_DONE_1|SECURE_BOOT_EN).*?\((0b[01]+)\)')
 
 
 @lru_cache()
@@ -72,10 +75,25 @@ def _filter_esptool_log(log: str) -> str:
     return new_log
 
 
+def check_flash_encrypted(efuse_summary: str) -> bool:
+    """Check whether flash encryption is enabled from efuse summary."""
+    match = FLASH_CRYPT_CNT_PATTERN.search(efuse_summary)
+    if match:
+        return match.group(1).count('1') % 2 == 1
+    return False
+
+
+def check_secure_boot_enabled(efuse_summary: str) -> bool:
+    """Check whether secure boot is enabled from efuse summary."""
+    match = SECURE_BOOT_EN_PATTERN.search(efuse_summary)
+    if match:
+        return match.group(1) == '0b1'
+    return False
+
+
 class DownBinTool:
     # RETRY_CNT = 2
     DEFAULT_BAUD_LIST = [921600, 460800]
-    FLASH_CRYPT_CNT_PATTERN = re.compile(r'(?:FLASH_CRYPT_CNT|SPI_BOOT_CRYPT_CNT).*\(0b([01]+)')
 
     def __init__(
         self,
@@ -101,12 +119,6 @@ class DownBinTool:
         self.force_no_stub = force_no_stub
         self.check_no_stub = check_no_stub
 
-    def check_flash_encrypted(self, efuse_summary: str) -> bool:
-        match = self.FLASH_CRYPT_CNT_PATTERN.search(efuse_summary)
-        if match:
-            return match.group(1).count('1') % 2 == 1
-        return False
-
     def download(self) -> None:
         efuse_cmd = self.espefuse.split()
         try:
@@ -116,8 +128,8 @@ class DownBinTool:
         except subprocess.CalledProcessError as err:
             logger.error(err.output)
             raise RuntimeError(f'Failed to get efuse information from {self.port}') from err
-
-        enc_indicator = ' [encrypted]' if self.check_flash_encrypted(summary) else ''
+        encrypted_indicator = ' [encrypted]' if check_flash_encrypted(summary) else ''
+        secure_boot_indicator = ' [secure_boot]' if check_secure_boot_enabled(summary) else ''
 
         download_log = ''
         for baud in self.baud_list:
@@ -133,16 +145,20 @@ class DownBinTool:
                     chip='auto',
                 )
                 if not esp.IS_STUB:  # type: ignore
+                    logger.debug(f'Add --no-stub for device: {self.port}')
                     args += ['--no-stub'] if '--no-stub' not in args else []
             args += ['-p', self.port]
             args += ['-b', f'{baud}']
-            args += self.bin_parser.flash_bin_args(erase_nvs=self.erase_nvs, encrypted=bool(enc_indicator))
+            args += self.bin_parser.flash_bin_args(
+                erase_nvs=self.erase_nvs, encrypted=bool(encrypted_indicator), secure_boot=bool(secure_boot_indicator)
+            )
 
-            logger.info(f'Downloading {self.port}@{baud}{enc_indicator}: {self.bin_path}')
+            logger.info(f'Downloading {self.port}@{baud}{encrypted_indicator}{secure_boot_indicator}: {self.bin_path}')
             logger.debug(f'esptool cmd: {" ".join(args)}')
             # get return code rather than check
             ret = subprocess.run(args, capture_output=True, text=True, check=False)
             if ret.returncode == 0:
+                logger.info(f'Download success: [{self.port}@{baud}]')
                 return  # succeed
             # failed
             download_log += f'esptool cmd failed ({ret.returncode}): ' + ' '.join(args)
@@ -193,3 +209,38 @@ def download_bin_to_ports(  # pylint: disable=too-many-positional-arguments
     check_no_stub: bool = False,
 ) -> None:
     asyncio.run(async_download_bin_scheduler(bin_path, ports, erase_nvs, max_workers, force_no_stub, check_no_stub))
+
+
+@dataclass
+class BinConfig:
+    bin_path: str
+    port: str
+    erase_nvs: bool = True
+    force_no_stub: bool = False
+    check_no_stub: bool = False
+
+
+async def async_downbin_scheduler(
+    bin_configs: t.List[BinConfig],
+    max_workers: int = 0,
+) -> None:
+    max_workers = max_workers or len(bin_configs)
+    loop = asyncio.get_running_loop()
+    loop.set_default_executor(concurrent.futures.ThreadPoolExecutor(max_workers=max_workers))
+
+    coroutines = []
+    for cfg in bin_configs:
+        down_tool = DownBinTool(
+            cfg.bin_path,
+            cfg.port,
+            erase_nvs=cfg.erase_nvs,
+            force_no_stub=cfg.force_no_stub,
+            check_no_stub=cfg.check_no_stub,
+        )
+        coroutines.append(_async_download_bin(down_tool, loop))
+
+    await asyncio.gather(*coroutines)
+
+
+def download_bins(bin_configs: t.List[BinConfig], max_workers: int = 0) -> None:
+    asyncio.run(async_downbin_scheduler(bin_configs, max_workers))

{esp_test_utils-0.3.1 → esp_test_utils-0.3.2}/esptest/utility/parse_bin_path.py

@@ -131,6 +131,7 @@ class ParseBinPath:
         self._parttool = parttool
         self._flasher_args: t.Dict[str, t.Any] = {}
         self._sdkconfig: SDKConfig = SDKConfig()
+        self._partition_table_csv_path: str = ''  # set when partition_table dir is read-only
 
     @property
     def sdkconfig(self) -> SDKConfig:
@@ -192,21 +193,39 @@ class ParseBinPath:
         """Check if esptool stub is used"""
         return bool(self.flasher_args['extra_esptool_args'].get('stub', False))
 
-    def _gen_partition_table(self) -> None:
+    @property
+    def partition_table_csv_path(self) -> Path:
+        """Get partition-table.csv path"""
+        if self._partition_table_csv_path:
+            return Path(self._partition_table_csv_path)
+        return Path(self.bin_path) / 'partition_table' / 'partition-table.csv'
+
+    def _gen_partition_table(self, part_csv: t.Optional[Path] = None) -> None:
         part_csv = Path(self.bin_path) / 'partition_table' / 'partition-table.csv'
         part_bin = Path(self.bin_path) / 'partition_table' / 'partition-table.bin'
-        if self.parttool_path and not part_csv.is_file() and part_bin.is_file():
-            try:
-                _cmd = ['python', self.parttool_path, str(part_bin), str(part_csv)]
-                subprocess.check_call(_cmd, shell=False)
-            except subprocess.SubprocessError as e:
-                logger.error(f'Failed to gen partition-table.csv: {str(e)}')
+        if part_csv.is_file():
+            # already exists
+            return
+        if not self.parttool_path or not part_bin.is_file():
+            logger.error('Can not gen partition-table.csv: parttool_path or partition-table.bin not found')
+            return
+        if not os.access(part_csv.parent, os.W_OK):
+            # partition_table dir is read-only, use tmp dir for .csv
+            part_csv = Path(tempfile.mktemp(suffix='.csv'))
+            self._partition_table_csv_path = str(part_csv)
+        logger.debug(f'Generating partition-table.csv to {part_csv}')
+        try:
+            _cmd = ['python', self.parttool_path, str(part_bin), str(part_csv)]
+            subprocess.check_call(_cmd, shell=False)
+        except subprocess.SubprocessError as e:
+            logger.error(f'Failed to gen partition-table.csv: {str(e)}')
+            raise e
 
     @lru_cache()
     def parse_partitions(self) -> t.List[PartitionInfo]:
         """Parse partitions from partition-table.csv"""
         self._gen_partition_table()
-        partition_table_file = Path(self.bin_path) / 'partition_table' / 'partition-table.csv'
+        partition_table_file = self.partition_table_csv_path
         if not partition_table_file.is_file():
             raise ValueError('Can not parse partition table')
         # # Name, Type, SubType, Offset, Size, Flags
@@ -287,17 +306,40 @@ class ParseBinPath:
         args += ['erase_flash']
         return args
 
-    def flash_bin_args(self, baudrate: int = 0, erase_nvs: bool = True, encrypted: bool = False) -> t.List[str]:
+    def _check_secure_boot_match(self, secure_boot: bool) -> None:
+        if secure_boot != self.sdkconfig.secure_boot_config:
+            msg = (
+                f'Secure Boot status mismatch! '
+                f'SDKConfig.secure_boot={self.sdkconfig.secure_boot_config}, '
+                f'efuse secure_boot_enabled={secure_boot}. '
+                f'Refusing to flash bin.'
+            )
+            raise RuntimeError(msg)
+
+    def flash_bin_args(
+        self,
+        baudrate: int = 0,
+        erase_nvs: bool = True,
+        encrypted: bool = False,
+        secure_boot: bool = False,
+    ) -> t.List[str]:
         """Get write_flash args / command for esptool.
 
         Args:
             baudrate (int, optional): baudrate for flashing.
             erase_nvs (bool, optional): whether to erase nvs partition.
             encrypted (bool, optional): whether to flash with encryption.
+            secure_boot (bool, optional): whether to flash with secure boot.
         """
         args = self._write_flash_args_common(baudrate)
         if encrypted:
             args += ['--encrypt']
+        if secure_boot:
+            # Secure Boot blocks writes to protected regions without --force
+            # Can't use idf.py flash, can use python -m esptool command in build_log
+            args += ['--force']
+        # always check secure boot match because efuse will be auto-flashed before idf v6.1 if secure boot is enabled
+        self._check_secure_boot_match(secure_boot)
         for offset, bin_file in self.flasher_args['flash_files'].items():
             args += [offset, str(Path(self.bin_path) / bin_file)]
         if erase_nvs:

esp_test_utils-0.3.2/tests/tools/test_download_bin.py

@@ -0,0 +1,81 @@
+from unittest import mock
+
+import esptest.tools.download_bin as download_bin_module
+from esptest.tools.download_bin import BinConfig, download_bin_to_ports, download_bins
+
+
+# 使用 patch.object(module, ...) 而非 patch('esptest.tools...')，避免 Py 3.7 下 esptest.tools 未加载时的 AttributeError
+# @mock.patch('esptest.tools.download_bin.DownBinTool')
+@mock.patch.object(download_bin_module, 'DownBinTool')
+def test_download_bin_to_ports_calls_down_tool_per_port(
+    mock_down_bin_tool: mock.MagicMock,
+) -> None:
+    """download_bin_to_ports 应对每个 port 用同一 bin_path 创建 DownBinTool 并调用 download。"""
+    bin_path = '/path/to/bin'
+    ports = ['/dev/ttyUSB0', '/dev/ttyUSB1']
+    download_bin_to_ports(bin_path, ports, erase_nvs=True, max_workers=2)
+    assert mock_down_bin_tool.call_count == 2
+    mock_down_bin_tool.assert_any_call(
+        bin_path, '/dev/ttyUSB0', erase_nvs=True, force_no_stub=False, check_no_stub=False
+    )
+    mock_down_bin_tool.assert_any_call(
+        bin_path, '/dev/ttyUSB1', erase_nvs=True, force_no_stub=False, check_no_stub=False
+    )
+    assert mock_down_bin_tool.return_value.download.call_count == 2
+
+
+@mock.patch.object(download_bin_module, 'DownBinTool')
+def test_download_bins_calls_down_tool_per_config(
+    mock_down_bin_tool: mock.MagicMock,
+) -> None:
+    """download_bins 应对每个 BinConfig 创建 DownBinTool 并调用 download。"""
+    configs = [
+        BinConfig(bin_path='/path/to/bin1', port='/dev/ttyUSB0'),
+        BinConfig(bin_path='/path/to/bin2', port='/dev/ttyUSB1', erase_nvs=False),
+    ]
+    download_bins(configs, max_workers=2)
+    assert mock_down_bin_tool.call_count == 2
+    mock_down_bin_tool.assert_any_call(
+        '/path/to/bin1', '/dev/ttyUSB0', erase_nvs=True, force_no_stub=False, check_no_stub=False
+    )
+    mock_down_bin_tool.assert_any_call(
+        '/path/to/bin2', '/dev/ttyUSB1', erase_nvs=False, force_no_stub=False, check_no_stub=False
+    )
+    assert mock_down_bin_tool.return_value.download.call_count == 2
+
+
+@mock.patch.object(download_bin_module, 'DownBinTool')
+def test_download_bins_empty_list(mock_down_bin_tool: mock.MagicMock) -> None:
+    """空配置列表时不应创建 DownBinTool，不抛错。"""
+    download_bins([], max_workers=1)
+    mock_down_bin_tool.assert_not_called()
+
+
+@mock.patch.object(download_bin_module, 'DownBinTool')
+def test_download_bins_default_max_workers(mock_down_bin_tool: mock.MagicMock) -> None:
+    """单配置时创建一次 DownBinTool 并调用 download。"""
+    configs = [BinConfig(bin_path='/bin/path', port='/dev/ttyUSB0')]
+    download_bins(configs)
+    mock_down_bin_tool.assert_called_once_with(
+        '/bin/path', '/dev/ttyUSB0', erase_nvs=True, force_no_stub=False, check_no_stub=False
+    )
+    mock_down_bin_tool.return_value.download.assert_called_once()
+
+
+@mock.patch.object(download_bin_module, 'DownBinTool')
+def test_download_bins_bin_config_options(mock_down_bin_tool: mock.MagicMock) -> None:
+    """BinConfig 的 erase_nvs/force_no_stub/check_no_stub 应传入 DownBinTool。"""
+    configs = [
+        BinConfig(
+            bin_path='/path/bin',
+            port='/dev/ttyUSB0',
+            erase_nvs=False,
+            force_no_stub=True,
+            check_no_stub=True,
+        ),
+    ]
+    download_bins(configs, max_workers=1)
+    mock_down_bin_tool.assert_called_once_with(
+        '/path/bin', '/dev/ttyUSB0', erase_nvs=False, force_no_stub=True, check_no_stub=True
+    )
+    mock_down_bin_tool.return_value.download.assert_called_once()

{esp_test_utils-0.3.1 → esp_test_utils-0.3.2}/tests/utility/test_parse_bin_path.py

@@ -2,6 +2,7 @@ import os
 import shutil
 import zipfile
 from pathlib import Path
+from unittest.mock import patch
 
 import pytest
 
@@ -135,6 +136,36 @@ def test_parse_bin_gen_part(test_bin_path: Path) -> None:
     assert set([p.name for p in partitions]) == set(['nvs', 'phy_init', 'factory', 'wpa2_cer', 'wpa2_key', 'wpa2_ca'])
 
 
+def test_parse_partitions_when_partition_table_dir_read_only(test_bin_path: Path) -> None:
+    """When partition_table dir is read-only, csv is generated in a tmp path and parse_partitions still works.
+    Use mock for os.access instead of real chmod so the test works in CI/Docker and on any filesystem.
+    """
+    part_dir = test_bin_path / 'partition_table'
+    partition_csv = part_dir / 'partition-table.csv'
+    partition_bin = part_dir / 'partition-table.bin'
+    assert partition_bin.is_file(), 'test data must have partition-table.bin'
+    os.remove(str(partition_csv))
+    assert not partition_csv.is_file()
+
+    real_access = os.access
+
+    def fake_access(path: Path, mode: int) -> bool:
+        if Path(path).resolve() == part_dir.resolve() and mode == os.W_OK:
+            return False
+        return real_access(path, mode)
+
+    # Patch os.access where it is used (global os module) to avoid AttributeError
+    # when 'esptest.utility' is not visible in the test environment.
+    with patch('os.access', side_effect=fake_access):
+        parser = ParseBinPath(test_bin_path)
+        partitions = parser.parse_partitions()
+
+    assert not partition_csv.is_file()  # csv file should not be created to read-only dir
+    assert len(partitions) == 6
+    assert set(p.name for p in partitions) == {'nvs', 'phy_init', 'factory', 'wpa2_cer', 'wpa2_key', 'wpa2_ca'}
+    assert parser.partition_table_csv_path  # attribute should be set
+
+
 def test_bin_path_to_dir() -> None:
     bin_path = bin_path_to_dir(str(TEST_FILE_PATH / 'test-bin.zip'))
     parse_bin_path = ParseBinPath(bin_path)