feat(esp_cli): move linux test to host_test and add test_apps

Author: SoucheSouche

README.md

@@ -1,7 +1,15 @@
-esp_cli/test_apps:
+esp_cli/host_test:
   enable:
     - if: IDF_TARGET == "linux"
       reason: "Sufficient to test on Linux target"
   disable:
     - if: IDF_VERSION_MAJOR <= 5 and IDF_VERSION_MINOR <= 4
-      reason: "those versions of esp-idf do not support eventfd for linux target"
+      reason: "those versions of esp-idf do not support eventfd for linux target"
+
+esp_cli/test_apps:
+  enable:
+    - if: IDF_TARGET == "esp32s3"
+      reason: "Need support for USB Serial JTAG"
+  disable:
+    - if: IDF_VERSION_MAJOR <= 5 and IDF_VERSION_MINOR <= 3
+      reason: "esp_vfs_fs_ops_t not available"

esp_cli/.build-test-rules.yml

@@ -0,0 +1,5 @@
+cmake_minimum_required(VERSION 3.22)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+set(COMPONENTS main)
+project(esp_cli_host_test)

esp_cli/host_test/CMakeLists.txt

@@ -0,0 +1,5 @@
+
+idf_component_register(SRCS "test_esp_cli.c" "test_main.c"
+                    PRIV_INCLUDE_DIRS "."
+                    PRIV_REQUIRES unity
+                    WHOLE_ARCHIVE)

esp_cli/host_test/main/CMakeLists.txt

@@ -0,0 +1,4 @@
+dependencies:
+  espressif/esp_cli:
+    version: "*"
+    override_path: "../.."

esp_cli/host_test/main/idf_component.yml

@@ -0,0 +1,332 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <string.h>
+#include <stdio.h>
+#include <fcntl.h>
+#include <sys/time.h>
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "freertos/semphr.h"
+#include "unity.h"
+#include "esp_cli.h"
+#include "esp_linenoise.h"
+#include "esp_cli_commands.h"
+
+#include <sys/socket.h>
+
+inline __attribute__((always_inline))
+uint32_t get_millis(void)
+{
+    struct timeval tv = { 0 };
+    gettimeofday(&tv, NULL);
+    return tv.tv_sec * 1000 + tv.tv_usec / 1000;
+}
+
+inline __attribute__((always_inline))
+void wait_ms(int ms)
+{
+    vTaskDelay(pdMS_TO_TICKS(ms));
+}
+
+static size_t s_on_enter_nb_of_calls = 0;
+static size_t s_pre_executor_nb_of_calls = 0;
+static size_t s_post_executor_nb_of_calls = 0;
+static size_t s_on_stop_nb_of_calls = 0;
+static size_t s_on_exit_nb_of_calls = 0;
+
+void test_on_enter(void *ctx, esp_cli_handle_t handle)
+{
+    s_on_enter_nb_of_calls++;
+    return;
+}
+
+esp_err_t test_pre_executor(void *ctx, const char *buf, esp_err_t reader_ret_val)
+{
+    s_pre_executor_nb_of_calls++;
+    return ESP_OK;
+}
+
+esp_err_t test_post_executor(void *ctx, const char *buf, esp_err_t executor_ret_val, int cmd_ret_val)
+{
+    s_post_executor_nb_of_calls++;
+    return ESP_OK;
+}
+
+void test_on_stop(void *ctx, esp_cli_handle_t handle)
+{
+    s_on_stop_nb_of_calls++;
+    return;
+}
+
+void test_on_exit(void *ctx, esp_cli_handle_t handle)
+{
+    s_on_exit_nb_of_calls++;
+    return;
+}
+
+/* Pass two semaphores:
+ *  - start_sem: child gives it when it reached esp_cli() (so main knows child started)
+ *  - done_sem:   child gives it just before deleting itself (so main can "join")
+ */
+typedef struct task_args {
+    SemaphoreHandle_t start_sem;
+    SemaphoreHandle_t done_sem;
+    esp_cli_handle_t hdl;
+} task_args_t;
+
+static void esp_cli_task(void *args)
+{
+    task_args_t *task_args = (task_args_t *)args;
+
+    /* signal to main that task started and esp_cli() will run */
+    xSemaphoreGive(task_args->start_sem);
+
+    /* run the esp_cli REPL loop (will return when stopped) */
+    esp_cli(task_args->hdl);
+
+    /* signal completion (emulates pthread_join notification) */
+    xSemaphoreGive(task_args->done_sem);
+
+    /* self-delete */
+    vTaskDelete(NULL);
+}
+
+static int s_socket_fd[2];
+
+static void test_socket_setup(int socket_fd[2])
+{
+    TEST_ASSERT_EQUAL(0, socketpair(AF_UNIX, SOCK_STREAM, 0, socket_fd));
+
+    /* ensure reads are blocking */
+    int flags = fcntl(socket_fd[0], F_GETFL, 0);
+    flags &= ~O_NONBLOCK;
+    fcntl(socket_fd[0], F_SETFL, flags);
+
+    flags = fcntl(socket_fd[1], F_GETFL, 0);
+    flags &= ~O_NONBLOCK;
+    fcntl(socket_fd[1], F_SETFL, flags);
+}
+
+static void test_socket_teardown(int socket_fd[2])
+{
+    close(socket_fd[0]);
+    close(socket_fd[1]);
+}
+
+static void test_send_characters(int socket_fd, const char *msg)
+{
+    wait_ms(100);
+
+    const size_t msg_len = strlen(msg);
+    const int nwrite = write(socket_fd, msg, msg_len);
+    TEST_ASSERT_EQUAL(msg_len, nwrite);
+}
+
+static void esp_cli_teardown(SemaphoreHandle_t *start_sem, SemaphoreHandle_t *done_sem, int socket_fd[2],
+                             esp_linenoise_handle_t *linenoise_hdl, esp_cli_handle_t *cli_hdl)
+{
+    /* destroy the instance of esp_cli */
+    TEST_ASSERT_EQUAL(ESP_OK, esp_cli_destroy(*cli_hdl));
+
+    /* delete the linenoise instance */
+    TEST_ASSERT_EQUAL(ESP_OK, esp_linenoise_delete_instance(*linenoise_hdl));
+
+    /* cleanup semaphores */
+    vSemaphoreDelete(*start_sem);
+    vSemaphoreDelete(*done_sem);
+
+    /* close the socketpair */
+    test_socket_teardown(socket_fd);
+
+    s_on_stop_nb_of_calls = 0;
+    s_on_exit_nb_of_calls = 0;
+    s_on_enter_nb_of_calls = 0;
+    s_pre_executor_nb_of_calls = 0;
+    s_post_executor_nb_of_calls = 0;
+}
+
+static void esp_cli_setup(SemaphoreHandle_t *start_sem, SemaphoreHandle_t *done_sem, int socket_fd[2],
+                          esp_linenoise_handle_t *linenoise_hdl, esp_cli_handle_t *cli_hdl)
+{
+    /* create semaphores */
+    *start_sem = xSemaphoreCreateBinary();
+    TEST_ASSERT_NOT_NULL(start_sem);
+    *done_sem = xSemaphoreCreateBinary();
+    TEST_ASSERT_NOT_NULL(done_sem);
+
+    /* create the socket_pair */
+    test_socket_setup(socket_fd);
+
+    /* ensure both semaphores are in the "taken/empty" state:
+    taking with 0 timeout guarantees they are empty afterwards
+    regardless of the create semantics on this FreeRTOS build. */
+    xSemaphoreTake(*start_sem, 0);
+    xSemaphoreTake(*done_sem, 0);
+
+    esp_linenoise_config_t linenoise_config;
+    esp_linenoise_get_instance_config_default(&linenoise_config);
+    linenoise_config.in_fd = socket_fd[0];
+    linenoise_config.out_fd = socket_fd[0];
+    TEST_ASSERT_EQUAL(ESP_OK, esp_linenoise_create_instance(&linenoise_config, linenoise_hdl));
+    TEST_ASSERT_NOT_NULL(*linenoise_hdl);
+
+    esp_cli_config_t cli_config = {
+        .linenoise_handle = *linenoise_hdl,
+        .command_set_handle = NULL,
+        .max_cmd_line_size = 256,
+        .history_save_path = NULL,
+        .on_enter = { .func = test_on_enter, .ctx = NULL },
+        .pre_executor = { .func = test_pre_executor, .ctx = NULL },
+        .post_executor = { .func = test_post_executor, .ctx = NULL },
+        .on_stop = { .func = test_on_stop, .ctx = NULL },
+        .on_exit = { .func = test_on_exit, .ctx = NULL }
+    };
+
+    TEST_ASSERT_EQUAL(ESP_OK, esp_cli_create(&cli_config, cli_hdl));
+    TEST_ASSERT_NOT_NULL(*cli_hdl);
+
+    s_on_stop_nb_of_calls = 0;
+    s_on_exit_nb_of_calls = 0;
+    s_on_enter_nb_of_calls = 0;
+    s_pre_executor_nb_of_calls = 0;
+    s_post_executor_nb_of_calls = 0;
+}
+
+TEST_CASE("esp_cli() loop calls all callbacks and exit on call to esp_cli_stop", "[esp_cli]")
+{
+    SemaphoreHandle_t start_sem, done_sem;
+    esp_linenoise_handle_t linenoise_hdl;
+    esp_cli_handle_t cli_hdl;
+    esp_cli_setup(&start_sem, &done_sem, s_socket_fd, &linenoise_hdl, &cli_hdl);
+
+    /* create the esp_cli instance task */
+    task_args_t args = {.start_sem = start_sem, .done_sem = done_sem, .hdl = cli_hdl};
+    BaseType_t rc = xTaskCreate(esp_cli_task, "esp_cli_task", 4096, &args, 5, NULL);
+    TEST_ASSERT_EQUAL(pdPASS, rc);
+
+    /* should fail before esp_cli instance is started */
+    TEST_ASSERT_NOT_EQUAL(ESP_OK, esp_cli_stop(cli_hdl));
+
+    /* start esp_cli instance */
+    TEST_ASSERT_NOT_EQUAL(ESP_OK, esp_cli_start(NULL));
+    TEST_ASSERT_EQUAL(ESP_OK, esp_cli_start(cli_hdl));
+
+    wait_ms(100);
+
+    /* wait for the esp_cli task to signal it started */
+    TEST_ASSERT_TRUE(xSemaphoreTake(start_sem, pdMS_TO_TICKS(2000)));
+
+    /* send a dummy string new line terminated to trigger linenoise to return */
+    const char *input_line = "dummy_message\n";
+    test_send_characters(s_socket_fd[1], input_line);
+
+    /* wait for a bit so esp_cli() has time to loop back into esp_linenoise_get_line */
+    wait_ms(500);
+
+    /* check that pre-executor, post-executor callbacks are called */
+    TEST_ASSERT_EQUAL(1, s_pre_executor_nb_of_calls);
+    TEST_ASSERT_EQUAL(1, s_post_executor_nb_of_calls);
+
+    /* stop esp_cli and wait for task to finish (emulate pthread_join) */
+    TEST_ASSERT_NOT_EQUAL(ESP_OK, esp_cli_stop(NULL));
+    TEST_ASSERT_EQUAL(ESP_OK, esp_cli_stop(cli_hdl));
+
+    /* wait for the esp_cli task to signal completion */
+    TEST_ASSERT_TRUE(xSemaphoreTake(done_sem, pdMS_TO_TICKS(2000)));
+
+    /* check that all callbacks were called the right number of times */
+    TEST_ASSERT_EQUAL(1, s_on_stop_nb_of_calls);
+    TEST_ASSERT_EQUAL(1, s_on_enter_nb_of_calls);
+    TEST_ASSERT_EQUAL(1, s_on_exit_nb_of_calls);
+    TEST_ASSERT_EQUAL(2, s_pre_executor_nb_of_calls);
+    TEST_ASSERT_EQUAL(2, s_post_executor_nb_of_calls);
+
+    /* make sure calling stop fails because the esp_cli instance is no longer running */
+    TEST_ASSERT_NOT_EQUAL(ESP_OK, esp_cli_stop(cli_hdl));
+
+    /* destroy the esp_cli instance */
+    TEST_ASSERT_NOT_EQUAL(ESP_OK, esp_cli_destroy(NULL));
+    esp_cli_teardown(&start_sem, &done_sem, s_socket_fd, &linenoise_hdl, &cli_hdl);
+}
+
+TEST_CASE("esp_cli() exits when esp_cli_stop() called from the task running esp_cli()", "[esp_cli]")
+{
+    SemaphoreHandle_t start_sem, done_sem;
+    esp_linenoise_handle_t linenoise_hdl;
+    esp_cli_handle_t cli_hdl;
+    esp_cli_setup(&start_sem, &done_sem, s_socket_fd, &linenoise_hdl, &cli_hdl);
+
+    /* create the esp_cli instance task */
+    task_args_t args = {.start_sem = start_sem, .done_sem = done_sem, .hdl = cli_hdl};
+    BaseType_t rc = xTaskCreate(esp_cli_task, "esp_cli_task", 4096, &args, 5, NULL);
+    TEST_ASSERT_EQUAL(pdPASS, rc);
+
+    /* start esp_cli instance */
+    TEST_ASSERT_EQUAL(ESP_OK, esp_cli_start(cli_hdl));
+
+    wait_ms(100);
+
+    /* wait for the esp_cli instance task to signal it started */
+    TEST_ASSERT_TRUE(xSemaphoreTake(start_sem, pdMS_TO_TICKS(2000)));
+
+    /* send the quit command */
+    const char *quit_cmd_line = "quit  \n";
+    test_send_characters(s_socket_fd[1], quit_cmd_line);
+
+    /* wait for the esp_cli instance task to signal completion */
+    TEST_ASSERT_TRUE(xSemaphoreTake(done_sem, pdMS_TO_TICKS(2000)));
+
+    esp_cli_teardown(&start_sem, &done_sem, s_socket_fd, &linenoise_hdl, &cli_hdl);
+}
+
+TEST_CASE("create and destroy several instances of esp_cli", "[esp_cli]")
+{
+    /* create semaphores */
+    SemaphoreHandle_t start_sem_a, start_sem_b;
+    SemaphoreHandle_t done_sem_a, done_sem_b;
+    esp_cli_handle_t cli_hdl_a, cli_hdl_b;
+    esp_linenoise_handle_t linenoise_hdl_a, linenoise_hdl_b;
+    int socket_fd_a[2], socket_fd_b[2];
+
+    /*  create 2 instances of esp_cli*/
+    esp_cli_setup(&start_sem_a, &done_sem_a, socket_fd_a, &linenoise_hdl_a, &cli_hdl_a);
+    esp_cli_setup(&start_sem_b, &done_sem_b, socket_fd_b, &linenoise_hdl_b, &cli_hdl_b);
+
+    /* create the esp_cli instance task A */
+    task_args_t args_a = {.start_sem = start_sem_a, .done_sem = done_sem_a, .hdl = cli_hdl_a};
+    BaseType_t rc = xTaskCreate(esp_cli_task, "esp_cli_task_a", 4096, &args_a, 5, NULL);
+    TEST_ASSERT_EQUAL(pdPASS, rc);
+
+    /* create the esp_cli instance task B */
+    task_args_t args_b = {.start_sem = start_sem_b, .done_sem = done_sem_b, .hdl = cli_hdl_b};
+    rc = xTaskCreate(esp_cli_task, "esp_cli_task_b", 4096, &args_b, 5, NULL);
+    TEST_ASSERT_EQUAL(pdPASS, rc);
+
+    /* start esp_cli instance */
+    TEST_ASSERT_EQUAL(ESP_OK, esp_cli_start(cli_hdl_a));
+    TEST_ASSERT_EQUAL(ESP_OK, esp_cli_start(cli_hdl_b));
+    wait_ms(500);
+
+    /* wait for the esp_cli instance tasks to signal it started */
+    TEST_ASSERT_TRUE(xSemaphoreTake(start_sem_a, pdMS_TO_TICKS(2000)));
+    TEST_ASSERT_TRUE(xSemaphoreTake(start_sem_b, pdMS_TO_TICKS(2000)));
+
+    /* terminate instance A */
+    TEST_ASSERT_EQUAL(ESP_OK, esp_cli_stop(cli_hdl_a));
+
+    /* wait for the esp_cli instance task to signal completion */
+    TEST_ASSERT_TRUE(xSemaphoreTake(done_sem_a, pdMS_TO_TICKS(2000)));
+
+    /* terminate instance B */
+    TEST_ASSERT_EQUAL(ESP_OK, esp_cli_stop(cli_hdl_b));
+
+    /* wait for the esp_cli instance task to signal completion */
+    TEST_ASSERT_TRUE(xSemaphoreTake(done_sem_b, pdMS_TO_TICKS(2000)));
+
+    esp_cli_teardown(&start_sem_a, &done_sem_a, socket_fd_a, &linenoise_hdl_a, &cli_hdl_a);
+    esp_cli_teardown(&start_sem_b, &done_sem_b, socket_fd_b, &linenoise_hdl_b, &cli_hdl_b);
+}