{"id":22796399,"url":"https://github.com/macmade/xstest","last_synced_at":"2025-04-19T13:08:39.296Z","repository":{"id":140403063,"uuid":"158626554","full_name":"macmade/XSTest","owner":"macmade","description":"C++ unit testing library","archived":false,"fork":false,"pushed_at":"2024-12-09T14:01:01.000Z","size":686,"stargazers_count":8,"open_issues_count":0,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-12-09T15:18:53.800Z","etag":null,"topics":["cplusplus","test","testing","unit-testing","visualstudio","xcode","xctest"],"latest_commit_sha":null,"homepage":null,"language":"C++","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/macmade.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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},"funding":{"github":"macmade"}},"created_at":"2018-11-22T01:30:43.000Z","updated_at":"2024-12-09T14:01:06.000Z","dependencies_parsed_at":"2024-05-07T16:40:58.290Z","dependency_job_id":"796ad5b6-b4e8-4aa8-85ed-9ea70f0522bf","html_url":"https://github.com/macmade/XSTest","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macmade%2FXSTest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macmade%2FXSTest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macmade%2FXSTest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macmade%2FXSTest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/macmade","download_url":"https://codeload.github.com/macmade/XSTest/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229333153,"owners_count":18056671,"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","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":["cplusplus","test","testing","unit-testing","visualstudio","xcode","xctest"],"created_at":"2024-12-12T05:12:48.632Z","updated_at":"2024-12-12T05:12:49.101Z","avatar_url":"https://github.com/macmade.png","language":"C++","funding_links":["https://github.com/sponsors/macmade"],"categories":[],"sub_categories":[],"readme":"XSTest\n======\n\n[![Build Status](https://img.shields.io/github/actions/workflow/status/macmade/XSTest/ci-mac.yaml?label=macOS\u0026logo=apple)](https://github.com/macmade/XSTest/actions/workflows/ci-mac.yaml)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/macmade/XSTest/ci-win.yaml?label=Windows\u0026logo=windows)](https://github.com/macmade/XSTest/actions/workflows/ci-win.yaml)\n[![Issues](http://img.shields.io/github/issues/macmade/XSTest.svg?logo=github)](https://github.com/macmade/XSTest/issues)\n![Status](https://img.shields.io/badge/status-active-brightgreen.svg?logo=git)\n![License](https://img.shields.io/badge/license-mit-brightgreen.svg?logo=open-source-initiative)  \n[![Contact](https://img.shields.io/badge/follow-@macmade-blue.svg?logo=twitter\u0026style=social)](https://twitter.com/macmade)\n[![Sponsor](https://img.shields.io/badge/sponsor-macmade-pink.svg?logo=github-sponsors\u0026style=social)](https://github.com/sponsors/macmade)\n\nAbout\n-----\n\n**XSTest is a cross-platform C++ unit testing library.**\n\n### Features\n\n - Cross-platform (macOS, Windows, Linux, Unix)\n - C++11 and greater\n - Header-only library\n - Integration with IDEs such as Xcode and VisualStudio\n - Compatible with GoogleTest\n\n![XSTest Example Output](Screenshots/Terminal.png \"XSTest Example Output\")\n\n### Primer\n\nXSTest is a header only library, meaning you simply need to include `XSTest/XSTest.hpp` in order to use-it.\n\nTest cases are defined using the `XTest` macro.  \nParameters are the test suite name and the test case name:\n\n```cpp\n#include \u003cXSTest/XSTest.hpp\u003e\n\nXSTest( MyTestSuite, MyTestCase )\n{\n    /* Test case body */\n}\n```\n\nNote that tests cases and test suites are run in random order for each invocation.\n\n#### Assertions\n\nTest case body is user-defined code, but the test case result is controlled using assertions macros:\n\n```cpp\n#include \u003cXSTest/XSTest.hpp\u003e\n\nXSTest( MyTestSuite, MyTestCase )\n{\n    XSTestAssertTrue( true );         /* Will succeed */\n    XSTestAssertEqual( true, false ); /* Will fail */\n}\n```\n\n#### Main function\n\nUsually, the unit tests are packaged into an executable.  \nYou can define a `main` function that will run all registered tests using:\n\n```cpp\n#define XSTEST_MAIN\n#include \u003cXSTest/XSTest.hpp\u003e\n\nint main( int argc, char * argv[] )\n{\n    return XS::Test::RunAll( { argc, argv } );\n}\n```\n\nPlease note the `XSTEST_MAIN` macro which is required in the `main` file before including the XSTest header.\n\nAs an alternative, you can define the `XSTEST_MAIN_RUN` macro.  \nThis will automatically generate a `main` function for you.\n\n```cpp\n#define XSTEST_MAIN_RUN\n#include \u003cXSTest/XSTest.hpp\u003e\n```\n\n#### Fixtures\n\nXSTest supports _fixtures_, that is test cases that will run from a user defined class representing the test suite.  \nThis allows custom setup to be performed prior to running a test case.\n\nFixtures requires a user-defined class, inheriting from `XS::Test::Case`, and are defined with the `XSTestFixture` macro:\n\n```cpp\n#include \u003cXSTest/XSTest.hpp\u003e\n\nclass MyFixture: XS::Test::Case\n{\n    protected:\n        \n        void SetUp() override\n        {\n            this-\u003e_x = 42;\n        }\n        \n        void TearDown() override\n        {}\n        \n        int _x = 0;\n};\n\nXSTestFixture( MyFixture, MyTestCase )\n{\n    XSTestAssertEqual( this-\u003e_x, 42 ); /* Will succeed */\n}\n```\n\nFor each test case, a new instance of the fixture class will be created.  \n`SetUp` and `TearDown` will be automatically called, allowing you to add custom behaviours to your test suite.\n\n#### Running selected tests\n\nWhen XSTest is run as an executable, you can specify which test you want to run by providing the names as command-line arguments:\n\n```sh\n./MyTestExecutable Foo Bar.Test1 Bar.Test2\n```\n\nIn the example above, all tests from the `Foo` suite will run, as well as `Test1` and `Test2` from the `Bar` suite.\n\n### IDE Integration\n\n#### Xcode\n\nXSTest provides a bridge for Xcode's XCTest framework, allowing you to run your tests and see the results directly from Xcode.\n\n![Xcode](Screenshots/Xcode-1.png \"Xcode\")\n\nIn order to use XSTest within Xcode, simply create a unit-test bundle and link with `XSTest.framework`, which is provided by the `XSTest.xcodeproj` project.\n\nThen, write your tests as usual, including XSTest's main header file:\n\n```cpp\n#include \u003cXSTest/XSTest.hpp\u003e\n```\n\nNote that in such a scenario, there's no need for a `main` function.\n\nYou can then run your tests. Test results will be reported to Xcode and displayed as usual:\n\n![Xcode](Screenshots/Xcode-2.png \"Xcode\")\n\n#### VisualStudio\n\n...\n\n### GoogleTest Compatibility\n\nXSTest aims to be compatible with GoogleTest, making it easy to migrate.\n\nMost assertions from GoogleTest can be used seamlessly with XSTest, by defining the `XSTEST_GTEST_COMPAT` macro:\n\n```cpp\n#define XSTEST_GTEST_COMPAT\n#include \u003cXSTest/XSTest.hpp\u003e\n\nTEST( MyTestSuite, MyTestCase )\n{\n    ASSERT_TRUE( true );\n}\n```\n\nSupported macros are:\n\n\nGoogleTest:                | Expands to:\n-------------------------- | ------\n`TEST`                     | `XSTest`\n`TEST_F`                   | `XSTestFixture`\n`ASSERT_TRUE`              | `XSTestAssertTrue`\n`ASSERT_FALSE`             | `XSTestAssertFalse`\n`ASSERT_EQ`                | `XSTestAssertEqual`\n`ASSERT_NE`                | `XSTestAssertNotEqual`\n`ASSERT_LT`                | `XSTestAssertLess`\n`ASSERT_LE`                | `XSTestAssertLessOrEqual`\n`ASSERT_GT`                | `XSTestAssertGreater`\n`ASSERT_GE`                | `XSTestAssertGreaterOrEqual`\n`ASSERT_STREQ`             | `XSTestAssertStringEqual`\n`ASSERT_STRNE`             | `XSTestAssertStringNotEqual`\n`ASSERT_STRCASEEQ`         | `XSTestAssertStringEqualCaseInsensitive`\n`ASSERT_STRCASENE`         | `XSTestAssertStringNotEqualCaseInsensitive`\n`ASSERT_THROW`             | `XSTestAssertThrow`\n`ASSERT_NO_THROW`          | `XSTestAssertNoThrow`\n`ASSERT_ANY_THROW`         | `XSTestAssertAnyThrow`\n`ASSERT_FLOAT_EQ`          | `XSTestAssertFloatEqual`\n`ASSERT_DOUBLE_EQ`         | `XSTestAssertDoubleEqual`\n`ASSERT_HRESULT_SUCCEEDED` | `XSTestAssertHResultSucceeded`\n`ASSERT_HRESULT_FAILED`    | `XSTestAssertHResultFailed`\n\n### Documentation\n\n#### Comparison assertions\n\nAssertion                                    | Verifies\n-------------------------------------------- | ----------------\n`XSTestAssertTrue( expr )`                   | `expr == true`\n`XSTestAssertFalse( expr )`                  | `expr == false`\n`XSTestAssertEqual( expr1, expr2 )`          | `expr1 == expr2`\n`XSTestAssertNotEqual( expr1, expr2 )`       | `expr1 != expr2`\n`XSTestAssertLess( expr1, expr2 )`           | `expr1 \u003c expr2`\n`XSTestAssertLessOrEqual( expr1, expr2 )`    | `expr1 \u003c= expr2`\n`XSTestAssertGreater( expr1, expr2 )`        | `expr1 \u003e expr2`\n`XSTestAssertGreaterOrEqual( expr1, expr2 )` | `expr1 \u003e= expr2`\n\n#### C string comparison assertions\n\nAssertion                                                   | Verifies\n----------------------------------------------------------- | --------------------------------------------------\n`XSTestAssertStringEqual( expr1, expr2 )`                   | If both C strings are equal (case sensitive)\n`XSTestAssertStringNotEqual( expr1, expr2 )`                | If both C strings are not equal (case sensitive)\n`XSTestAssertStringEqualCaseInsensitive( expr1, expr2 )`    | If both C strings are equal (case insensitive)\n`XSTestAssertStringNotEqualCaseInsensitive( expr1, expr2 )` | If both C strings are not equal (case insensitive)\n\n#### Exception assertions\n\nAssertion                           | Verifies\n------------------------------------| -------------------------------------------------\n`XSTestAssertThrow( expr, except )` | If `expr` throws a C++ exception of type `except`\n`XSTestAssertNoThrow( expr )`       | If `expr` doesn't any C++ exception\n`XSTestAssertAnyThrow( expr )`      | If `expr` throws a C++ exception\n\n#### Floating point comparison assertions\n\nAssertion                                 | Verifies\n------------------------------------------| -----------------------------------------------\n`XSTestAssertFloatEqual( expr1, expr2 )`  | If both `float` values can be considered equal\n`XSTestAssertDoubleEqual( expr1, expr2 )` | If both `double` values can be considered equal\n\n*Note: Floating point values are considered equal if they are within 4 ULPs from each other.*  \n*Value of 4 ULPs is used to keep compatibility with GoogleTest, which uses the same value.*\n\n#### Windows specific assertions\n\nAssertion                              | Verifies\n---------------------------------------| -------------------------------------------------\n`XSTestAssertHResultSucceeded( expr )` | If `expr` is a valid `HRESULT`\n`XSTestAssertHResultFailed( expr )`    | If `expr` is not a valid `HRESULT`\n\nLicense\n-------\n\nXSTest is released under the terms of the MIT license.\n\nRepository Infos\n----------------\n\n    Owner:          Jean-David Gadina - XS-Labs\n    Web:            www.xs-labs.com\n    Blog:           www.noxeos.com\n    Twitter:        @macmade\n    GitHub:         github.com/macmade\n    LinkedIn:       ch.linkedin.com/in/macmade/\n    StackOverflow:  stackoverflow.com/users/182676/macmade\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmacmade%2Fxstest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmacmade%2Fxstest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmacmade%2Fxstest/lists"}