{"id":16962504,"url":"https://github.com/threeal/assertion-cmake","last_synced_at":"2026-02-13T13:07:56.621Z","repository":{"id":237703098,"uuid":"795085708","full_name":"threeal/assertion-cmake","owner":"threeal","description":"A CMake module containing a collection of assertion functions and other utilities for testing CMake code","archived":false,"fork":false,"pushed_at":"2025-07-08T13:03:32.000Z","size":290,"stargazers_count":6,"open_issues_count":4,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-08T14:23:17.794Z","etag":null,"topics":["assert","assertions","cmake","cmake-modules","cmake-scripts","test","testing"],"latest_commit_sha":null,"homepage":"","language":"CMake","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/threeal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-05-02T14:56:55.000Z","updated_at":"2025-07-08T13:03:34.000Z","dependencies_parsed_at":"2024-05-28T10:04:29.087Z","dependency_job_id":"e7a3a47d-5c9c-4812-a041-ce1209f1bf32","html_url":"https://github.com/threeal/assertion-cmake","commit_stats":null,"previous_names":["threeal/assertion-cmake"],"tags_count":7,"template":false,"template_full_name":"threeal/cmake-starter","purl":"pkg:github/threeal/assertion-cmake","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/threeal%2Fassertion-cmake","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/threeal%2Fassertion-cmake/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/threeal%2Fassertion-cmake/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/threeal%2Fassertion-cmake/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/threeal","download_url":"https://codeload.github.com/threeal/assertion-cmake/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/threeal%2Fassertion-cmake/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266768249,"owners_count":23981351,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assert","assertions","cmake","cmake-modules","cmake-scripts","test","testing"],"created_at":"2024-10-13T23:06:57.422Z","updated_at":"2026-02-13T13:07:56.598Z","avatar_url":"https://github.com/threeal.png","language":"CMake","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Assertion.cmake\n\nA [CMake](https://cmake.org/) module containing a collection of assertion functions and other utilities for testing CMake code.\n\nThe main feature of this module is the [`assert`](#assert) function, which asserts the given condition in the style of CMake's [`if`](https://cmake.org/cmake/help/latest/command/if.html) function. If the assertion fails, it throws a fatal error message with information about the context of the asserted condition.\n\nThis module also supports [CMake test](https://cmake.org/cmake/help/book/mastering-cmake/chapter/Testing%20With%20CMake%20and%20CTest.html) creation using the [`add_cmake_script_test`](#add_cmake_script_test) function. This function creates a new test that processes a CMake file containing tests in script mode.\n\n## Key Features\n\n- Supports condition, command call, and process execution assertions.\n- Supports test creation that processes a CMake file.\n- Simple syntax and easy integration.\n\n## Usage Guide\n\n### Module Integration\n\nThe recommended way to integrate this module into a project is by downloading it during the project configuration using the [`file(DOWNLOAD)`](https://cmake.org/cmake/help/latest/command/file.html#download) function:\n\n```cmake\nfile(DOWNLOAD https://github.com/threeal/assertion-cmake/releases/download/v2.0.0/Assertion.cmake\n    ${CMAKE_BINARY_DIR}/cmake/Assertion.cmake\n  EXPECTED_MD5 5ebe475aee6fc5660633152f815ce9f6)\n\ninclude(${CMAKE_BINARY_DIR}/cmake/Assertion.cmake)\n```\n\nAlternatively, to support offline mode, this module can also be vendored directly into a project and included normally using the [`include`](https://cmake.org/cmake/help/latest/command/include.html) function.\n\n### Assertion Example\n\nThere are three functions provided by this module that can be used to perform assertions in CMake code:\n\n- [`assert`](#assert): Performs an assertion on the given condition.\n- [`assert_call`](#assert_call): Performs an assertion on the given command call.\n- [`assert_execute_process`](#assert_execute_process): Performs an assertion on a process executed with the given command.\n\nFor example, given the following `git_clone` function for cloning a Git repository from the given `URL` and setting the `OUTPUT_VAR` with the path of the cloned Git repository directory:\n\n```cmake\nfunction(git_clone URL OUTPUT_VAR)\n  string(REGEX REPLACE \".*/\" \"\" DIRECTORY \"${URL}\")\n  execute_process(COMMAND git clone \"${URL}\" \"${DIRECTORY}\" RESULT_VARIABLE RES)\n  if(NOT RES EQUAL 0)\n    message(FATAL_ERROR \"failed to clone '${URL}' (${RES})\")\n  endif()\n\n  set(\"${OUTPUT_VAR}\" \"${DIRECTORY}\" PARENT_SCOPE)\nendfunction()\n```\n\nYou can create the following assertions to verify if it can successfully clone a Git repository and correctly set the output variable:\n\n```cmake\ngit_clone(https://github.com/threeal/cmake-starter CMAKE_STARTER_DIR)\n\nassert(DEFINED CMAKE_STARTER_DIR)\nassert(EXISTS \"${CMAKE_STARTER_DIR}\")\n```\n\nYou can further verify if the output variable contains a correct Git directory and if it correctly throws an error on failure:\n\n```cmake\nassert(IS_DIRECTORY \"${CMAKE_STARTER_DIR}\")\nassert_execute_process(\n  git -C \"${CMAKE_STARTER_DIR}\" rev-parse --is-inside-work-tree)\n\nassert_call(git_clone https://invalid.com INVALID_DIR\n  EXPECT_ERROR \"failed to clone 'https://invalid.com'\")\n```\n\n### Test Creation\n\nIn CMake, tests are normally created using the [`add_test`](https://cmake.org/cmake/help/latest/command/add_test.html) function and run separately from the project configuration and build processes. To simplify test creation, this module provides an [`add_cmake_script_test`](#add_cmake_script_test) function.\n\nGiven a file named `test_git_checkout.cmake` that contains assertions for a `git_clone` function, you can create a new test target that will process that file as follows:\n\n```cmake\nadd_cmake_script_test(test_git_checkout.cmake NAME \"Test Git checkout\")\n```\n\nThe above line creates a new test target named \"Test Git checkout\" that will process the `git_checkout_test.cmake` file in script mode.\n\n## API Reference\n\n### `ASSERTION_VERSION`\n\nThis variable contains the version of the included `Assertion.cmake` module.\n\n### `add_cmake_script_test`\n\nAdds a new test that processes the given CMake file in script mode.\n\n```cmake\nadd_cmake_script_test(\n  [FILE] \u003cfile\u003e [NAME \u003cname\u003e] [DEFINITIONS \u003cvariables\u003e...])\n```\n\nThis function adds a new test that processes the specified `\u003cfile\u003e` in script mode. If `NAME` is provided, `\u003cname\u003e` will be used as the test name; otherwise, the test name will default to `\u003cfile\u003e`.\n\nIf the `CMAKE_SCRIPT_TEST_DEFINITIONS` variable is defined, the script will be processed with the predefined variables listed in that variable. Each entry should be in the format `\u003cname\u003e=\u003cvalue\u003e`, where `\u003cname\u003e` is the variable name and `\u003cvalue\u003e` is its value. If `\u003cvalue\u003e` is not provided, it uses the value of a variable named `\u003cname\u003e` in the current CMake scope. If `DEFINITIONS` is specified, additional variables will also be defined.\n\n#### Example\n\n```cmake\nset(BAR bar)\nadd_cmake_script_test(test_foo.cmake NAME \"Test Foo\" DEFINITIONS FOO=foo BAR)\n```\n\nThe example above adds a new test named `Test Foo`, which processes the `test_foo.cmake` file in script mode with predefined `FOO` and `BAR` variables.\n\n### `fail`\n\nThrows a formatted fatal error message.\n\n```cmake\nfail(\u003clines\u003e...)\n```\n\nThis macro throws a fatal error message formatted from the given `\u003clines\u003e`.\n\nIt formats the message by concatenating all the lines into a single message. If one of the lines is a variable, it will be expanded and indented by two spaces before being concatenated with the other lines. If the expanded variable is another variable, it will format both the name and the value of the other variable.\n\n#### Example\n\n```cmake\nset(COMMAND \"cmd arg0 arg1 arg2\")\nset(REASON \"unknown reason\")\n\nfail(\"something happened when executing\" COMMAND \"because of\" REASON)\n```\n\nThe above example throws a fatal error message formatted as follows:\n\n```\nsomething happened when executing:\n  cmd arg0 arg1 arg2\nbecause of:\n  unknown reason\n```\n\n### `assert`\n\nPerforms an assertion on the given condition.\n\n```cmake\nassert(\u003ccondition\u003e...)\n```\n\nThis function performs an assertion on the given `\u003ccondition\u003e`. If the assertion fails, it will output a formatted fatal error message with information about the context of the asserted condition.\n\nInternally, this function uses CMake's [`if`](https://cmake.org/cmake/help/latest/command/if.html) function to check the given condition and throws a fatal error message if the condition resolves to false. Refer to CMake's `if` function documentation for more information about supported conditions for the assertion.\n\n#### Example\n\n```cmake\nassert(DEFINED EXECUTABLE_PATH)\nassert(IS_EXECUTABLE \"${EXECUTABLE_PATH}\")\n```\n\nThe above example asserts whether the `EXECUTABLE_PATH` variable is defined and resolves to the path of an executable. If the variable is not defined, it will throw the following fatal error message:\n\n```\nexpected variable:\n  EXECUTABLE_PATH\nto be defined\n```\n\n### `assert_call`\n\nPerforms an assertion on the given command call.\n\n```cmake\nassert_call(\n  [CALL] \u003ccommand\u003e [\u003carguments\u003e...]\n  [EXPECT_ERROR [MATCHES|STREQUAL] \u003cmessage\u003e...]\n  [EXPECT_WARNING [MATCHES|STREQUAL] \u003cmessage\u003e...])\n```\n\nThis function asserts whether the function or macro named `\u003ccommand\u003e`, called with the specified `\u003carguments\u003e`, does not receive any errors or warnings. Internally, the function captures all errors and warnings from CMake's [`message`](https://cmake.org/cmake/help/latest/command/message.html) function. Each captured error and warning is concatenated with new lines as separators.\n\nIf `EXPECT_ERROR` or `EXPECT_WARNING` is specified, it instead asserts whether the call to the function or macro received errors or warnings that satisfy the expected message.\n\nIn both `EXPECT_ERROR` and `EXPECT_WARNING` options, `MATCHES` and `STREQUAL` are used to determine the operator for comparing the received errors and warnings with the expected message. If `MATCHES` is specified, they are compared using regular expression matching. If `STREQUAL` is specified, they are compared lexicographically. If neither is specified, it defaults to `MATCHES`.\n\nIf more than one `\u003cmessage\u003e` string is given, they are concatenated into a single message with no separators.\n\n#### Example\n\n```cmake\nfunction(send_errors)\n  foreach(MESSAGE IN LISTS ARGN)\n    message(SEND_ERROR \"${MESSAGE} error\")\n  endforeach()\nendfunction()\n\nassert_call(\n  CALL send_errors first second\n  EXPECT_ERROR STREQUAL \"first error\\nsecond error\")\n```\n\nThe above example asserts whether the call to `send_errors(first second)` receives errors equal to `first error\\nsecond error`. If it does not receive any errors, it will throw the following error:\n\n```\nexpected to receive errors\n```\n\n### `assert_execute_process`\n\nPerforms an assertion on a process executed with the given command.\n\n```cmake\nassert_execute_process(\n  [COMMAND] \u003ccommand\u003e [\u003carguments\u003e...]\n  [EXPECT_FAIL]\n  [EXPECT_OUTPUT [MATCHES|STREQUAL] \u003cmessage\u003e...]\n  [EXPECT_ERROR [MATCHES|STREQUAL] \u003cmessage\u003e...])\n```\n\nThis function asserts whether the given `\u003ccommand\u003e` and `\u003carguments\u003e` successfully execute a process. If `EXPECT_FAIL` or `EXPECT_ERROR` is specified, it asserts that the process fails to execute.\n\nIf `EXPECT_OUTPUT` or `EXPECT_ERROR` is specified, it also asserts whether the output or error of the executed process matches the expected message.\n\nIn both `EXPECT_OUTPUT` and `EXPECT_ERROR` options, `MATCHES` and `STREQUAL` are used to determine the operator for comparing the received output and error with the expected message. If `MATCHES` is specified, they are compared using regular expression matching. If `STREQUAL` is specified, they are compared lexicographically. If neither is specified, it defaults to `MATCHES`.\n\nIf more than one `\u003cmessage\u003e` string is given, they are concatenated into a single message with no separators.\n\n#### Example\n\n```cmake\nassert_execute_process(\n  COMMAND ${CMAKE_COMMAND} -E echo hello\n  EXPECT_OUTPUT hello)\n```\n\nThe above example asserts that the call to `${CMAKE_COMMAND} -E echo hello` successfully executes a process whose output is equal to `hello`. If the process fails to execute, it will throw the following fatal error message:\n\n```\nexpected command:\n  /path/to/cmake -E echo hello\nnot to fail with error:\n  unknown error\n```\n\n### `section`\n\nBegins a new test section.\n\n```cmake\nsection(\u003cname\u003e...)\n```\n\nThis function begins a new test section named `\u003cname\u003e`. It prints the test section name and indents all subsequent messages by two spaces.\n\nIf more than one `\u003cname\u003e` string is given, they are concatenated into a single name with no separator between the strings.\n\nUse the [`endsection`](#endsection) function to end the test section.\n\n#### Example\n\n```cmake\nsection(\"test something\")\n  section(\"it should not fail\")\n    message(STATUS \"nothing happened\")\n  endsection()\n\n  section(\"it should fail because something might happen\")\n    fail(\"something happened\")\n  endsection()\nendsection()\n```\n\nThe above example begins several test sections. If processed, it will output the following lines:\n\n```\n-- test something\n--   it should not fail\n--     nothing happened\n--   it should fail because something might happen\nCMake Error (message):\n  something happened\n```\n\n### `endsection`\n\nEnds the current test section.\n\n```cmake\nendsection()\n```\n\nThis function ends the current test section.\n\n## License\n\nThis project is licensed under the terms of the [MIT License](./LICENSE).\n\nCopyright © 2024-2026 [Alfi Maulana](https://github.com/threeal)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthreeal%2Fassertion-cmake","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthreeal%2Fassertion-cmake","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthreeal%2Fassertion-cmake/lists"}