🔀 Merge branch 'main' into update-docs

Author: NestorDP

CMakeLists.txt

@@ -140,6 +140,7 @@ if(BUILD_TESTING)
     add_executable(serial_tests
         test/test_serial_simple.cpp
         test/test_serial_pty.cpp
+        test/test_ports.cpp
     )
 
     target_include_directories(serial_tests PRIVATE

docs/api_reference.rst

@@ -12,14 +12,28 @@ Classes
 .. doxygenclass:: libserial::Ports
    :members:
 
+.. doxygenclass:: libserial::Device
+   :members:
+
 Exceptions
 ----------
 
 .. doxygenclass:: libserial::SerialException
    :members:
 
-Data Structures
----------------
+Enumerations
+------------
+
+.. doxygenenum:: libserial::Parity
+
+.. doxygenenum:: libserial::StopBits
+
+.. doxygenenum:: libserial::FlowControl
+
+.. doxygenenum:: libserial::CanonicalMode
+
+.. doxygenenum:: libserial::Terminator
+
+.. doxygenenum:: libserial::BaudRate
 
-.. doxygenstruct:: libserial::DeviceStruct
-   :members:
+.. doxygenenum:: libserial::DataLength

include/libserial/ports.hpp

@@ -40,6 +40,15 @@ class Ports {
  */
 Ports() = default;
 
+/**
+ * @brief Testable constructor allowing a custom system path
+ *
+ * Primarily intended for testing to inject a non-existent or
+ * non-readable directory to validate error handling paths.
+ */
+explicit Ports(const char* sys_path) : sys_path_(sys_path) {
+}
+
 /**
  * @brief Destroyer of the Ports class
  *
@@ -50,9 +59,7 @@ Ports() = default;
  * @brief Scans the system for available serial ports
  *
  * @return uint16_t The number of serial ports found
- * @throws SerialException if scanning fails
  * @throws SerialException if no ports are found
- * @throws PermissionDeniedException if insufficient permissions
  */
 uint16_t scanPorts();
 
@@ -98,6 +105,11 @@ std::optional<std::string> findName(uint16_t id) const;
  */
 static constexpr const char* kSysSerialByIdPath = "/dev/serial/by-id/";
 
+/**
+ * @brief Configurable path used by scanPorts; defaults to kSysSerialByIdPath
+ */
+const char* sys_path_ { kSysSerialByIdPath };
+
 /**
  * @brief Internal list of detected serial devices
  */

include/libserial/serial_exception.hpp

@@ -20,16 +20,73 @@ namespace libserial {
  */
 class SerialException : public std::exception {
 public:
-explicit SerialException(std::string message) : message_(std::move(message)) {
+explicit SerialException(std::string message)
+  : message_(std::move(message)) {
 }
-
 const char* what() const noexcept override {
   return message_.c_str();
 }
-
 private:
-std::string message_;  // NOLINT(runtime/string)
-};
+std::string message_;
+};  // class SerialException
+
+/**
+ * @class PortNotFoundException
+ * @brief Exception class for port not found errors
+ *
+ * The PortNotFoundException class is derived from SerialException
+ * and is used to indicate that a specified serial port could not be found.
+ */
+class PortNotFoundException : public SerialException {
+public:
+explicit PortNotFoundException(std::string message)
+  : SerialException(std::move(message)) {
+}
+};  // class PortNotFoundException
+
+/**
+ * @class PermissionDeniedException
+ * @brief Exception class for permission denied errors
+ *
+ * The PermissionDeniedException class is derived from SerialException
+ * and is used to indicate that permission to access a specified serial port was denied.
+ */
+class PermissionDeniedException : public SerialException {
+public:
+explicit PermissionDeniedException(std::string message)
+  : SerialException(std::move(message)) {
+}
+};  // class PermissionDeniedException
+
+/**
+ * @class TimeoutException
+ * @brief Exception class for timeout errors
+ *
+ * The TimeoutException class is derived from SerialException
+ * and is used to indicate that a serial port operation has timed out.
+ */
+class TimeoutException : public SerialException {
+public:
+explicit TimeoutException(std::string message)
+  : SerialException(std::move(message)) {
+}
+};  // class TimeoutException
+
+/**
+ * @class IOException
+ * @brief Exception class for I/O errors
+ *
+ * The IOException class is derived from SerialException
+ * and is used to indicate that an I/O error has occurred during
+ * serial port operations.
+ */
+class IOException : public SerialException {
+public:
+explicit IOException(std::string message)
+  : SerialException(std::move(message)) {
+}
+};  // class IOException
+
 }  // namespace libserial
 
 #endif  // INCLUDE_LIBSERIAL_SERIAL_EXCEPTION_HPP_

src/ports.cpp

@@ -23,11 +23,11 @@ uint16_t Ports::scanPorts() {
 
   // Directory where udev creates symlinks for serial devices by ID
   // this directory may not exist if no serial devices are connected
-  const char* by_id_dir = kSysSerialByIdPath;
+  const char* by_id_dir = sys_path_;
   DIR* dir = opendir(by_id_dir);
   if (!dir) {
-    std::cout << "No serial devices directory: " << by_id_dir << "\n";
-    return -1;
+    throw PortNotFoundException("Error while reading " + std::string(by_id_dir) + ": " +
+                                strerror(errno));
   }
 
   // The POSIX directory-entry structure used by readdir() to describe files

test/test_ports.cpp

@@ -0,0 +1,96 @@
+// Copyright 2020-2025 Nestor Neto
+
+#include <gtest/gtest.h>
+#include <cstdlib>
+#include <cstring>
+#include <dirent.h>
+#include <unistd.h>
+#include <memory>
+#include <string>
+#include <iostream>
+
+#include "libserial/ports.hpp"
+#include "libserial/serial_exception.hpp"
+
+// Simple unit tests that don't require actual hardware
+class PortsTest : public ::testing::Test {
+protected:
+void SetUp() override {
+  char temp_template[] = "/tmp/fake_serial_XXXXXX";
+  ASSERT_NE(mkdtemp(temp_template), nullptr) << "Failed to create temp directory";
+  temp_dir_ = temp_template;
+}
+
+void TearDown() override {
+  // Clean up all symlinks in temp_dir_
+  DIR* dir = opendir(temp_dir_.c_str());
+  if (dir) {
+    struct dirent* entry;
+    while ((entry = readdir(dir)) != nullptr) {
+      if (entry->d_name[0] != '.') {
+        std::string path = temp_dir_ + "/" + entry->d_name;
+        unlink(path.c_str());
+      }
+    }
+    closedir(dir);
+  }
+  rmdir(temp_dir_.c_str());
+}
+
+std::string temp_dir_;
+};
+
+TEST_F(PortsTest, DefaultConstructor) {
+  EXPECT_NO_THROW({
+    libserial::Ports ports;
+  });
+}
+
+TEST_F(PortsTest, ScanPortsThrowsWhenPathMissing) {
+  // Use an unlikely path to exist to trigger the exception path
+  const char* missing_path = "/this/path/should/not/exist/serial/by-id";
+  libserial::Ports ports(missing_path);
+
+
+  try {
+    (void)ports.scanPorts();
+    FAIL() << "Expected libserial::SerialException to be thrown";
+  }
+  catch (const libserial::SerialException& e) {
+    std::cout << "Caught SerialException: " << e.what() << std::endl;
+    // Optionally assert something about the message:
+    EXPECT_NE(std::string(e.what()).find("Error while reading"), std::string::npos);
+  }
+  catch (...) {
+    FAIL() << "Expected libserial::SerialException, but got a different exception";
+  }
+}
+
+TEST_F(PortsTest, ScanPortsWithFakeDevices) {
+  // Create fake device symlinks
+  std::string fake_device1 = std::string(temp_dir_) + "/usb-FTDI_FT232R_USB_UART_A1B2C3D4";
+  std::string fake_device2 = std::string(temp_dir_) + "/usb-Arduino_Uno_12345678";
+
+  // Create symlinks pointing to fake /dev/ttyUSB* paths
+  // The actual target doesn't need to exist for scanPorts to process it
+  ASSERT_EQ(symlink("../../ttyUSB0", fake_device1.c_str()), 0);
+  ASSERT_EQ(symlink("../../ttyUSB1", fake_device2.c_str()), 0);
+
+  // Test scanPorts with the fake directory
+  libserial::Ports ports(temp_dir_.c_str());
+  uint16_t count = 0;
+  EXPECT_NO_THROW({
+    count = ports.scanPorts();
+  });
+
+  EXPECT_EQ(count, 2) << "Should find 2 fake devices";
+
+  EXPECT_EQ(ports.findName(1).value(), "usb-FTDI_FT232R_USB_UART_A1B2C3D4");
+  EXPECT_EQ(ports.findName(0).value(), "usb-Arduino_Uno_12345678");
+  EXPECT_EQ(ports.findPortPath(1).value(), "/dev/ttyUSB0");
+  EXPECT_EQ(ports.findPortPath(0).value(), "/dev/ttyUSB1");
+  EXPECT_EQ(ports.findBusPath(1).value(), "/dev/ttyUSB0");
+  EXPECT_EQ(ports.findBusPath(0).value(), "/dev/ttyUSB1");
+}
+
+