framework-criterion

# AI Skill: Criterion Testing Specialist in C (Criterion Specialist) This skill guides the AI to act as a **QA and C software engineering specialist focused on the Criterion framework**. Its goal is to guide the creation of modern, safe, and concise C unit test suites (C99, C11, C17, C23), covering memory assertions, signal and system testing, standard input/output redirection, and integration with CMake/Meson pipelines. --- ## 🧭 Criterion Principles and Architecture When using Criterion in C code projects: - **Clean, Declarative Syntax**: Use the `Test(suite_name, test_name)` macro to define suites and tests without writing `main()` functions or registering tests manually. - **Assertions and Expectations**: - `cr_assert_*`: Immediately aborts the current test if the condition is false. - `cr_expect_*`: Marks the failure in the final report but lets the test keep running. - **Process Isolation**: Criterion runs each test in a separate isolated process through `fork()`. A crash (such as a `SIGSEGV` from a null pointer) in one test does not abort the whole suite. - **Native I/O Redirection**: Test `stdout` and `stderr` output by capturing file descriptors natively. --- ## 🛠️ Practical Engineering Guidelines and Code Standards ### 1. Unit Testing C Functions (`cr_assert_eq`, `cr_assert_str_eq`) - Use typed comparison macros for detailed error messages. ```c #include <criterion/criterion.h> #include <criterion/new/assert.h> #include "calculator.h" Test(calculator_suite, test_add_positive_numbers) { int result = add(15, 25); cr_assert_eq(result, 40, "Expected 40, but got %d", result); } Test(calculator_suite, test_string_formatting) { char *formatted = format_currency(100.50); cr_assert_str_eq(formatted, "$100.50", "Incorrect formatted string: %s", formatted); free(formatted); // Memory cleanup } ``` ### 2. Life-Cycle Configuration (`.init` and `.fini`) - Define setup (`.init`) and teardown (`.fini`) functions directly in the extra parameters of the `Test` macro. ```c #include <criterion/criterion.h> #include <stdio.h> #include "database_driver.h" static DBConnection *db_conn = NULL; void setup_db(void) { db_conn = db_connect("sqlite::memory:"); db_create_tables(db_conn); } void teardown_db(void) { if (db_conn) { db_disconnect(db_conn); db_conn = NULL; } } Test(database_suite, test_insert_record, .init = setup_db, .fini = teardown_db) { cr_assert_not_null(db_conn, "The database connection must be active."); int status = db_insert(db_conn, "users", "Alice"); cr_assert_eq(status, DB_SUCCESS, "Failed to insert record."); } ``` ### 3. Signal, Crash, and Timeout Testing (`.signal` and `.timeout`) - Make sure defensive C functions handle null pointers or raise `SIGSEGV`/`SIGABRT` where appropriate. ```c #include <criterion/criterion.h> #include <signal.h> #include "utils.h" // Test expects the function to throw a Segmentation Fault if it receives a null pointer Test(safety_suite, test_null_pointer_crash, .signal = SIGSEGV) { process_buffer(NULL, 100); } // Test is canceled if it takes longer than 1.5 seconds Test(performance_suite, test_infinite_loop_prevention, .timeout = 1.5) { compute_complex_hash("payload"); } ``` ### 4. Standard Output Testing (`stdout` / `stderr`) - Redirect and validate data printed with `printf`. ```c #include <criterion/criterion.h> #include <criterion/redirect.h> #include <stdio.h> void setup_redirects(void) { cr_redirect_stdout(); cr_redirect_stderr(); } Test(cli_suite, test_print_welcome_message, .init = setup_redirects) { puts("Welcome to the System!"); cr_assert_stdout_eq_str("Welcome to the System!\n"); } ``` --- ## ⚙️ Build System Integration (CMakeLists.txt) ```cmake cmake_minimum_required(VERSION 3.14) project(c_project_tests C) set(CMAKE_C_STANDARD 11) find_package(PkgConfig REQUIRED) pkg_check_modules(CRITERION REQUIRED criterion) add_executable(run_tests tests/test_main.c src/calculator.c ) target_include_directories(run_tests PRIVATE src/ ${CRITERION_INCLUDE_DIRS}) target_link_libraries(run_tests PRIVATE ${CRITERION_LIBRARIES}) enable_testing() add_test(NAME criterion_tests COMMAND run_tests) ``` --- ## 🔗 Integration with Other Skills - [lang-c](../../languages/lang-c/SKILL.md): Ensures compliance with C standards (C11/C17), prevention of undefined behavior (UB), and memory management. - [qa-engineer](../../roles/qa-engineer/SKILL.md): Guides the design of unit test suites for embedded software and low-level systems. - [framework-testing](../framework-testing/SKILL.md): Provides the theoretical concepts of TDD and the test pyramid.