pytest-embedded-serial 2.3.0__tar.gz

pytest_embedded_serial-2.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Espressif Systems (Shanghai) Co. Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pytest_embedded_serial-2.3.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: pytest-embedded-serial
+Version: 2.3.0
+Summary: Make pytest-embedded plugin work with Serial.
+Author-email: Fu Hanxi <fuhanxi@espressif.com>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python
+Classifier: Topic :: Software Development :: Testing
+License-File: LICENSE
+Requires-Dist: pytest-embedded~=2.3.0
+Requires-Dist: pyserial~=3.0
+Project-URL: changelog, https://github.com/espressif/pytest-embedded/blob/main/CHANGELOG.md
+Project-URL: documentation, https://docs.espressif.com/projects/pytest-embedded/en/latest/
+Project-URL: homepage, https://github.com/espressif/pytest-embedded
+Project-URL: repository, https://github.com/espressif/pytest-embedded
+
+### pytest-embedded-serial
+
+pytest embedded service for testing via serial ports
+
+Extra Functionalities:
+
+- `serial`: enable the fixture
+- `dut`: duplicate the `serial` output to `pexpect_proc`.
+

pytest_embedded_serial-2.3.0/README.md

@@ -0,0 +1,8 @@
+### pytest-embedded-serial
+
+pytest embedded service for testing via serial ports
+
+Extra Functionalities:
+
+- `serial`: enable the fixture
+- `dut`: duplicate the `serial` output to `pexpect_proc`.

pytest_embedded_serial-2.3.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["flit_core >=3.2,<4"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "pytest-embedded-serial"
+authors = [
+    {name = "Fu Hanxi", email = "fuhanxi@espressif.com"},
+]
+readme = "README.md"
+license = {file = "LICENSE"}
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Framework :: Pytest",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python",
+    "Topic :: Software Development :: Testing",
+]
+dynamic = ["version", "description"]
+requires-python = ">=3.10"
+
+dependencies = [
+    "pytest-embedded~=2.3.0",
+    "pyserial~=3.0",
+]
+
+[project.urls]
+homepage = "https://github.com/espressif/pytest-embedded"
+repository = "https://github.com/espressif/pytest-embedded"
+documentation = "https://docs.espressif.com/projects/pytest-embedded/en/latest/"
+changelog = "https://github.com/espressif/pytest-embedded/blob/main/CHANGELOG.md"

pytest_embedded_serial-2.3.0/pytest_embedded_serial/__init__.py

@@ -0,0 +1,11 @@
+"""Make pytest-embedded plugin work with Serial."""
+
+from .dut import SerialDut
+from .serial import Serial
+
+__all__ = [
+    'Serial',
+    'SerialDut',
+]
+
+__version__ = '2.3.0'

pytest_embedded_serial-2.3.0/pytest_embedded_serial/dut.py

@@ -0,0 +1,46 @@
+from typing import TYPE_CHECKING, AnyStr, Optional
+
+from pytest_embedded.dut import Dut
+from pytest_embedded.utils import to_bytes
+
+from .serial import Serial
+
+if TYPE_CHECKING:
+    from pytest_embedded_jtag import Gdb, OpenOcd, Telnet
+
+
+class SerialDut(Dut):
+    """
+    Dut class for serial ports
+
+    Attributes:
+        serial (Serial): `Serial` instance
+        openocd (OpenOcd): `OpenOcd` instance, applied only when `jtag` service is activated
+        gdb (Gdb): `Gdb` instance, applied only when `jtag` service is activated
+        telnet (Telnet): `Telnet` instance, applied only when `jtag` service is activated
+    """
+
+    def __init__(
+        self,
+        serial: Serial,
+        openocd: Optional['OpenOcd'] = None,
+        gdb: Optional['Gdb'] = None,
+        telnet: Optional['Telnet'] = None,
+        **kwargs,
+    ) -> None:
+        super().__init__(**kwargs)
+
+        self.serial = serial
+        self.openocd = openocd
+        self.gdb = gdb
+        self.telnet = telnet
+
+        self.setup_jtag()
+
+    def write(self, data: AnyStr) -> None:
+        self.serial.proc.write(to_bytes(data, '\n'))
+
+    def setup_jtag(self):
+        if self.gdb:
+            self.gdb.write('set remotetimeout 10')
+            self.gdb.write(f'target extended-remote :{self.openocd.gdb_port}')

pytest_embedded_serial-2.3.0/pytest_embedded_serial/serial.py

@@ -0,0 +1,267 @@
+import contextlib
+import copy
+import logging
+import multiprocessing
+import queue
+import threading
+import time
+from typing import Any, ClassVar
+
+import serial as pyserial
+from pytest_embedded.log import MessageQueue
+from pytest_embedded.utils import Meta
+from serial.tools import list_ports
+
+
+class Serial:
+    """
+    Custom serial class
+
+    Attributes:
+        port (str): port address
+        baud (int): baud rate
+        proc (pyserial.Serial): process created by `serial.serial_for_url()`
+
+    Warning:
+        - make sure this `Serial.__init__()` run the last in MRO, it would create and start the redirect serial process
+    """
+
+    DEFAULT_BAUDRATE = 115200
+
+    DEFAULT_PORT_CONFIG: ClassVar[dict[str, Any]] = {
+        'baudrate': DEFAULT_BAUDRATE,
+        'bytesize': pyserial.EIGHTBITS,
+        'parity': pyserial.PARITY_NONE,
+        'stopbits': pyserial.STOPBITS_ONE,
+        'timeout': 0.05,  # read timeout
+        'xonxoff': False,
+        'rtscts': False,
+    }
+
+    occupied_ports: ClassVar[dict[str, None]] = dict()
+
+    def __init__(
+        self,
+        msg_queue: MessageQueue,
+        port: str | None = None,
+        port_location: str | None = None,
+        baud: int = DEFAULT_BAUDRATE,
+        meta: Meta | None = None,
+        stop_after_init: bool = False,
+        ports_to_occupy: list[str] = (),
+        **kwargs,
+    ):
+        self._q = msg_queue
+        self._meta = meta
+        self._redirect_thread: _SerialRedirectThread = None  # type: ignore
+
+        self.baud = baud
+        self.ports_to_occupy = ports_to_occupy if ports_to_occupy else []
+
+        if isinstance(port, pyserial.SerialBase):
+            self.proc = port
+            self.proc.timeout = self.DEFAULT_PORT_CONFIG['timeout']  # set read timeout
+            self.port = self.proc.port
+        else:
+            # Need to detect or create instance
+            if port_location:
+                for _port in list_ports.comports():
+                    if _port.device in self.occupied_ports:
+                        continue
+                    if _port.location == port_location:
+                        if port and _port.device != port:
+                            raise ValueError(
+                                f'The specified location {port_location} binds with port {_port.device}, not {port}'
+                            )
+
+                        self.port = _port.device
+                        break
+                else:
+                    raise ValueError(f'The specified location {port_location} cannot be found.')
+            elif port:
+                self.port = port
+            else:
+                raise ValueError('Please specify port or provide the port location')
+
+            self.port = port
+            port_config = copy.deepcopy(self.DEFAULT_PORT_CONFIG)
+            port_config['baudrate'] = baud
+            port_config.update(**kwargs)
+            self.proc = pyserial.serial_for_url(self.port, **port_config)
+
+        self.ports_to_occupy.append(self.port)
+        self._post_init()
+        try:
+            self._start()
+        except Exception as e:
+            self.close()
+            raise e
+        self._finalize_init()
+        if not stop_after_init:
+            self.start_redirect_thread()
+        else:
+            self.close()
+
+    def start_redirect_thread(self) -> None:
+        if self._redirect_thread and self._redirect_thread.is_alive():
+            return
+
+        # Here the reason why we're still using thread is,
+        # the `pyserial` object can't be pickled when using multiprocessing.Process
+        self._redirect_thread = _SerialRedirectThread(self._q, self.proc)
+        self._redirect_thread.start()
+
+    def stop_redirect_thread(self) -> bool:
+        killed = False
+        if self._redirect_thread and self._redirect_thread.is_alive():
+            self._redirect_thread.terminate()
+            killed = True
+
+        return killed
+
+    def _post_init(self):
+        pass
+
+    def _start(self):
+        pass
+
+    def _finalize_init(self):
+        occupied_ports = []
+        for port in self.ports_to_occupy:
+            if port not in self.occupied_ports:
+                self.occupied_ports[port] = None
+                occupied_ports.append(port)
+                logging.debug(f'occupied {port}')
+            else:
+                logging.warning(f'port {port} is already occupied')
+        self.ports_to_occupy = occupied_ports
+
+    def close(self):
+        self.stop_redirect_thread()
+        self.proc.close()
+        for port in self.ports_to_occupy:
+            self.occupied_ports.pop(port, None)
+            logging.debug(f'released {port}')
+
+    @contextlib.contextmanager
+    def disable_redirect_thread(self) -> bool:
+        """
+        kill the redirect thread, and start a new one after got yield back
+
+        Yields:
+            True if redirect serial thread has been terminated
+        """
+        killed = self.stop_redirect_thread()
+
+        yield killed
+
+        if killed:
+            self.start_redirect_thread()
+
+
+class _SerialRedirectThread(threading.Thread):
+    """
+    Redirect serial thread
+    """
+
+    def __init__(self, msg_queue: MessageQueue, s: pyserial.Serial):
+        self._q = msg_queue
+        self._event_q = multiprocessing.Queue()
+        self._s = s
+
+        self._block_reading = False
+
+        super().__init__(target=self._event_loop, daemon=True)  # killed by the main process
+
+    def _event_loop(self):
+        """
+        Since pyserial.Serial instance can't be serialized, we pass the `_serial` as an reference of the object
+        defined in _forward_io. The pyserial.Serial methods are mocked to send an event to the queue, and the real
+        method is running here.
+        """
+        while True:
+            try:
+                _e = self._event_q.get_nowait()
+            except queue.Empty:
+                _e = 'read'
+            except OSError:
+                return
+
+            if _e == 'read':
+                if self._block_reading:
+                    continue
+
+                try:
+                    s = self._s.read_all()
+                except OSError as e:
+                    logging.error(f'OSError detected: {e}. Serial connection may be lost.')
+                    if self._s.closed:
+                        logging.error('Serial port is already closed. Exiting event loop.')
+                        return
+
+                    port = self._s.port
+                    port_config = {
+                        'baudrate': self._s.baudrate,
+                        'bytesize': self._s.bytesize,
+                        'parity': self._s.parity,
+                        'stopbits': self._s.stopbits,
+                        'timeout': self._s.timeout,
+                        'xonxoff': self._s.xonxoff,
+                        'rtscts': self._s.rtscts,
+                    }
+                    for attempt in range(1, 4):
+                        delay = attempt * 1.5
+                        logging.warning(
+                            f'Attempting to reconnect to serial port {port} (try {attempt}/3) after {delay}s...'
+                        )
+                        time.sleep(delay)
+                        try:
+                            self._s.close()
+                            self._s = pyserial.serial_for_url(port, **port_config)
+                            logging.info(f'Successfully reconnected to serial port {port}.')
+                            break
+                        except Exception as e:
+                            logging.warning(f'Reconnection attempt {attempt} failed: {e}')
+                    else:
+                        logging.error(
+                            f'Failed to reconnect to serial port {port} after 3 attempts. Exiting event loop.'
+                        )
+                        return
+
+                    continue
+
+                except Exception as e:
+                    logging.warning(
+                        'unknown error: %s.\nRecommend to close the serial process by `dut.serial.close()`', str(e)
+                    )
+                    return
+
+                try:
+                    self._q.put(s)
+                except OSError as e:
+                    logging.warning(f'OSError. Error msg: {e}')
+                    return
+                except Exception as e:
+                    logging.warning(
+                        'unknown error: %s.\nRecommend to close the serial process by `dut.serial.close()`', str(e)
+                    )
+                    return
+
+            elif _e == 'stop':
+                self._block_reading = True
+            elif _e == 'start':
+                self._block_reading = False
+            elif _e == 'end':
+                return
+
+            time.sleep(0.05)  # set interval
+
+    def stop_reading(self):
+        self._event_q.put('stop')
+
+    def start_reading(self):
+        self._event_q.put('start')
+
+    def terminate(self):
+        self._event_q.put('end')
+        self.join()

pytest_embedded_serial-2.3.0/tests/test_serial.py

@@ -0,0 +1,117 @@
+import sys
+
+import pytest
+
+
+def test_custom_serial_device(testdir):
+    testdir.makepyfile(r"""
+        import pytest
+
+        def test_serial_mixed(dut):
+            from pytest_embedded.dut_factory import DutFactory
+            assert len(dut)==2
+            another_dut = DutFactory.create()
+            st = set(
+                (
+                    dut[0].serial.port,
+                    dut[1].serial.port,
+                    another_dut.serial.port
+                )
+            )
+            assert len(st) == 3
+
+        def test_custom_dut():
+            from pytest_embedded.dut_factory import DutFactory
+            another_dut = DutFactory.create(embedded_services='esp,serial')
+    """)
+
+    result = testdir.runpytest(
+        '-s',
+        '--embedded-services',
+        'esp,serial',
+        '--count',
+        2,
+    )
+    result.assert_outcomes(passed=2, errors=0)
+
+
+def test_custom_serial_device_dut_count_1(testdir):
+    testdir.makepyfile(r"""
+        import pytest
+
+        def test_serial_device_created_dut_count_1(dut):
+            from pytest_embedded.dut_factory import DutFactory
+            another_dut = DutFactory.create()
+            another_dut2 = DutFactory.create()
+            st = set(
+                (
+                    dut.serial.port,
+                    another_dut.serial.port,
+                    another_dut2.serial.port
+                )
+            )
+            assert len(st) == 3
+
+
+    """)
+
+    result = testdir.runpytest(
+        '-s',
+        '--embedded-services',
+        'esp,serial',
+        '--count',
+        1,
+    )
+    result.assert_outcomes(passed=1, errors=0)
+
+
+@pytest.mark.skipif(sys.platform == 'win32', reason='No socat support on windows')
+@pytest.mark.flaky(reruns=3, reruns_delay=2)
+def test_serial_port(testdir):
+    testdir.makepyfile(r"""
+        import pytest
+        import subprocess
+
+        @pytest.fixture(autouse=True)
+        def open_tcp_port():
+            proc = subprocess.Popen('socat TCP4-LISTEN:9876,fork EXEC:cat', shell=True)
+            yield
+            proc.terminate()
+
+        def test_serial_port(dut):
+            dut.write(b'hello world\n')
+            dut.expect('hello world')
+    """)
+
+    result = testdir.runpytest(
+        '-s',
+        '--embedded-services',
+        'serial',
+        '--port',
+        'socket://localhost:9876',
+    )
+
+    result.assert_outcomes(passed=1)
+
+
+def test_teardown_called_for_multi_dut(testdir):
+    testdir.makepyfile(r"""
+        import pytest
+
+        @pytest.mark.parametrize('count, embedded_services, port', [
+            ('3', 'serial', '/dev/ttyUSB0|/dev/ttyUSB1|/dev/ttyUSB100'),  # set up failure
+        ], indirect=True)
+        def test_teardown_called_for_multi_dut_fail(dut):
+            assert len(dut) == 3
+
+        @pytest.mark.parametrize('count, embedded_services, port', [
+            ('3', 'serial', '/dev/ttyUSB0|/dev/ttyUSB1|/dev/ttyUSB2'),  # set up succeeded
+        ], indirect=True)
+        def test_teardown_called_for_multi_dut_succeeded(dut):
+            assert dut[0].serial.port == '/dev/ttyUSB0'
+            assert dut[1].serial.port == '/dev/ttyUSB1'
+            assert dut[2].serial.port == '/dev/ttyUSB2'
+    """)
+
+    result = testdir.runpytest()
+    result.assert_outcomes(passed=1, errors=1)