From 020a531e4b1969178c9bd1c002fef443b35225fb Mon Sep 17 00:00:00 2001 From: Kyle Krueger Date: Fri, 7 Sep 2018 14:33:51 +0200 Subject: [PATCH 1/2] add link to test_runner file --- docs/UnityGettingStartedGuide.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/UnityGettingStartedGuide.md b/docs/UnityGettingStartedGuide.md index 5e4427c..b774ae4 100644 --- a/docs/UnityGettingStartedGuide.md +++ b/docs/UnityGettingStartedGuide.md @@ -114,10 +114,10 @@ call. Remembering to add each test to the main function can get to be tedious. If you enjoy using helper scripts in your build process, you might consider making use -of our handy generate_test_runner.rb script. This will create the main function -and all the calls for you, assuming that you have followed the suggested naming -conventions. In this case, there is no need for you to include the main function -in your test file at all. +of our handy [generate_test_runner.rb](../auto/generate_test_runner.rb) script. +This will create the main function and all the calls for you, assuming that you +have followed the suggested naming conventions. In this case, there is no need +for you to include the main function in your test file at all. When you're done, your test file will look something like this: @@ -141,6 +141,7 @@ void test_function_should_doAlsoDoBlah(void) { //more test stuff } +// not needed when using generate_test_runner.rb int main(void) { UNITY_BEGIN(); RUN_TEST(test_function_should_doBlahAndBlah); From ea5e51ffccf8ac0b3c09db2b5b85a27e66bcb76d Mon Sep 17 00:00:00 2001 From: Kyle Krueger Date: Fri, 7 Sep 2018 14:46:20 +0200 Subject: [PATCH 2/2] move some details from main readme to docs, and link to getting started --- README.md | 50 +++------------------------- docs/UnityGettingStartedGuide.md | 57 ++++++++++++++++++++++++++++++++ 2 files changed, 62 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index ec73b4a..cb37731 100644 --- a/README.md +++ b/README.md @@ -4,54 +4,14 @@ Unity Test API [![Unity Build Status](https://api.travis-ci.org/ThrowTheSwitch/Unity.png?branch=master)](https://travis-ci.org/ThrowTheSwitch/Unity) __Copyright (c) 2007 - 2017 Unity Project by Mike Karlesky, Mark VanderVoord, and Greg Williams__ -Running Tests -------------- - - RUN_TEST(func, linenum) - -Each Test is run within the macro `RUN_TEST`. This macro performs necessary setup before the test is called and handles cleanup and result tabulation afterwards. - -Ignoring Tests --------------- - -There are times when a test is incomplete or not valid for some reason. At these times, TEST_IGNORE can be called. Control will immediately be returned to the caller of the test, and no failures will be returned. - - TEST_IGNORE() - -Ignore this test and return immediately - - TEST_IGNORE_MESSAGE (message) - -Ignore this test and return immediately. Output a message stating why the test was ignored. - -Aborting Tests --------------- - -There are times when a test will contain an infinite loop on error conditions, or there may be reason to escape from the test early without executing the rest of the test. A pair of macros support this functionality in Unity. The first `TEST_PROTECT` sets up the feature, and handles emergency abort cases. `TEST_ABORT` can then be used at any time within the tests to return to the last `TEST_PROTECT` call. - - TEST_PROTECT() - -Setup and Catch macro - - TEST_ABORT() - -Abort Test macro - -Example: - - main() - { - if (TEST_PROTECT()) - { - MyTest(); - } - } - -If MyTest calls `TEST_ABORT`, program control will immediately return to `TEST_PROTECT` with a return value of zero. - +Getting Started +=============== +The [docs](docs/) folder contains a [getting started guide](docs/UnityGettingStartedGuide.md) +and much more tips about using Unity. Unity Assertion Summary ======================= +For the full list, see [UnityAssertionsReference.md](docs/UnityAssertionsReference.md). Basic Validity Tests -------------------- diff --git a/docs/UnityGettingStartedGuide.md b/docs/UnityGettingStartedGuide.md index b774ae4..eb7041d 100644 --- a/docs/UnityGettingStartedGuide.md +++ b/docs/UnityGettingStartedGuide.md @@ -154,6 +154,63 @@ It's possible that you will need more customization than this, eventually. For that sort of thing, you're going to want to look at the configuration guide. This should be enough to get you going, though. +### Running Test Functions +When writing your own `main()` functions, for a test-runner. There are two ways +to execute the test. + +The classic variant +``` c +RUN_TEST(func, linenum) +``` +or its simpler replacement that starts at the beginning of the function. +``` c +RUN_TEST(func) +``` +These macros perform the necessary setup before the test is called and +handles cleanup and result tabulation afterwards. + +### Ignoring Test Functions +There are times when a test is incomplete or not valid for some reason. +At these times, TEST_IGNORE can be called. Control will immediately be +returned to the caller of the test, and no failures will be returned. +This is useful when your test runners are automatically generated. + +``` c +TEST_IGNORE() +``` + +Ignore this test and return immediately + +``` c +TEST_IGNORE_MESSAGE (message) +``` + +Ignore this test and return immediately. Output a message stating why the test was ignored. + +### Aborting Tests +There are times when a test will contain an infinite loop on error conditions, or there may be reason to escape from the test early without executing the rest of the test. A pair of macros support this functionality in Unity. The first `TEST_PROTECT` sets up the feature, and handles emergency abort cases. `TEST_ABORT` can then be used at any time within the tests to return to the last `TEST_PROTECT` call. + + TEST_PROTECT() + +Setup and Catch macro + + TEST_ABORT() + +Abort Test macro + +Example: + + main() + { + if (TEST_PROTECT()) + { + MyTest(); + } + } + +If MyTest calls `TEST_ABORT`, program control will immediately return to `TEST_PROTECT` with a return value of zero. + + ## How to Build and Run A Test File