mirror of
https://github.com/ThrowTheSwitch/Unity.git
synced 2025-05-23 02:17:27 +08:00
Add newlines after headings for best practice, trim trailing spaces & convert sneaky incorrectly coded chars
blank newline after headins is apparently best practice according to http://stackoverflow.com/q/42953462/1292918
This commit is contained in:
toby
@ -1,151 +1,168 @@
|
||||
# Unity - Getting Started
|
||||
|
||||
## Welcome
|
||||
Congratulations. You're now the proud owner of your very own pile of bits! What
|
||||
are you going to do with all these ones and zeros? This document should be able
|
||||
|
||||
Congratulations. You're now the proud owner of your very own pile of bits! What
|
||||
are you going to do with all these ones and zeros? This document should be able
|
||||
to help you decide just that.
|
||||
|
||||
Unity is a unit test framework. The goal has been to keep it small and
|
||||
functional. The core Unity test framework is three files: a single C file and a
|
||||
couple header files. These team up to provide functions and macros to make
|
||||
Unity is a unit test framework. The goal has been to keep it small and
|
||||
functional. The core Unity test framework is three files: a single C file and a
|
||||
couple header files. These team up to provide functions and macros to make
|
||||
testing easier.
|
||||
|
||||
Unity was designed to be cross platform. It works hard to stick with C standards
|
||||
while still providing support for the many embedded C compilers that bend the
|
||||
rules. Unity has been used with many compilers, including GCC, IAR, Clang,
|
||||
Green Hills, Microchip, and MS Visual Studio. It's not much work to get it to
|
||||
Unity was designed to be cross platform. It works hard to stick with C standards
|
||||
while still providing support for the many embedded C compilers that bend the
|
||||
rules. Unity has been used with many compilers, including GCC, IAR, Clang,
|
||||
Green Hills, Microchip, and MS Visual Studio. It's not much work to get it to
|
||||
work with a new target.
|
||||
|
||||
|
||||
### Overview of the Documents
|
||||
|
||||
#### Unity Assertions reference
|
||||
This document will guide you through all the assertion options provided by
|
||||
Unity. This is going to be your unit testing bread and butter. You'll spend more
|
||||
|
||||
This document will guide you through all the assertion options provided by
|
||||
Unity. This is going to be your unit testing bread and butter. You'll spend more
|
||||
time with assertions than any other part of Unity.
|
||||
|
||||
|
||||
#### Unity Assertions Cheat Sheet
|
||||
This document contains an abridged summary of the assertions described in the
|
||||
previous document. It's perfect for printing and referencing while you
|
||||
|
||||
This document contains an abridged summary of the assertions described in the
|
||||
previous document. It's perfect for printing and referencing while you
|
||||
familiarize yourself with Unity's options.
|
||||
|
||||
|
||||
#### Unity Configuration Guide
|
||||
This document is the one to reference when you are going to use Unity with a new
|
||||
target or compiler. It'll guide you through the configuration options and will
|
||||
|
||||
This document is the one to reference when you are going to use Unity with a new
|
||||
target or compiler. It'll guide you through the configuration options and will
|
||||
help you customize your testing experience to meet your needs.
|
||||
|
||||
|
||||
#### Unity Helper Scripts
|
||||
This document describes the helper scripts that are available for simplifying
|
||||
your testing workflow. It describes the collection of optional Ruby scripts
|
||||
included in the auto directory of your Unity installation. Neither Ruby nor
|
||||
these scripts are necessary for using Unity. They are provided as a convenience
|
||||
|
||||
This document describes the helper scripts that are available for simplifying
|
||||
your testing workflow. It describes the collection of optional Ruby scripts
|
||||
included in the auto directory of your Unity installation. Neither Ruby nor
|
||||
these scripts are necessary for using Unity. They are provided as a convenience
|
||||
for those who wish to use them.
|
||||
|
||||
|
||||
#### Unity License
|
||||
What's an open source project without a license file? This brief document
|
||||
describes the terms you're agreeing to when you use this software. Basically, we
|
||||
want it to be useful to you in whatever context you want to use it, but please
|
||||
|
||||
What's an open source project without a license file? This brief document
|
||||
describes the terms you're agreeing to when you use this software. Basically, we
|
||||
want it to be useful to you in whatever context you want to use it, but please
|
||||
don't blame us if you run into problems.
|
||||
|
||||
|
||||
### Overview of the Folders
|
||||
If you have obtained Unity through Github or something similar, you might be
|
||||
|
||||
If you have obtained Unity through Github or something similar, you might be
|
||||
surprised by just how much stuff you suddenly have staring you in the face.
|
||||
Don't worry, Unity itself is very small. The rest of it is just there to make
|
||||
your life easier. You can ignore it or use it at your convenience. Here's an
|
||||
Don't worry, Unity itself is very small. The rest of it is just there to make
|
||||
your life easier. You can ignore it or use it at your convenience. Here's an
|
||||
overview of everything in the project.
|
||||
|
||||
- `src` — This is the code you care about! This folder contains a C file and two
|
||||
- `src` - This is the code you care about! This folder contains a C file and two
|
||||
header files. These three files _are_ Unity.
|
||||
- `docs` — You're reading this document, so it's possible you have found your way
|
||||
into this folder already. This is where all the handy documentation can be
|
||||
- `docs` - You're reading this document, so it's possible you have found your way
|
||||
into this folder already. This is where all the handy documentation can be
|
||||
found.
|
||||
- `examples` — This contains a few examples of using Unity.
|
||||
- `extras` — These are optional add ons to Unity that are not part of the core
|
||||
project. If you've reached us through James Grenning's book, you're going to
|
||||
- `examples` - This contains a few examples of using Unity.
|
||||
- `extras` - These are optional add ons to Unity that are not part of the core
|
||||
project. If you've reached us through James Grenning's book, you're going to
|
||||
want to look here.
|
||||
- `test` — This is how Unity and its scripts are all tested. If you're just using
|
||||
Unity, you'll likely never need to go in here. If you are the lucky team member
|
||||
who gets to port Unity to a new toolchain, this is a good place to verify
|
||||
- `test` - This is how Unity and its scripts are all tested. If you're just using
|
||||
Unity, you'll likely never need to go in here. If you are the lucky team member
|
||||
who gets to port Unity to a new toolchain, this is a good place to verify
|
||||
everything is configured properly.
|
||||
- `auto` — Here you will find helpful Ruby scripts for simplifying your test
|
||||
- `auto` - Here you will find helpful Ruby scripts for simplifying your test
|
||||
workflow. They are purely optional and are not required to make use of Unity.
|
||||
|
||||
## How to Create A Test File
|
||||
Test files are C files. Most often you will create a single test file for each C
|
||||
module that you want to test. The test file should include unity.h and the
|
||||
|
||||
## How to Create A Test File
|
||||
|
||||
Test files are C files. Most often you will create a single test file for each C
|
||||
module that you want to test. The test file should include unity.h and the
|
||||
header for your C module to be tested.
|
||||
|
||||
Next, a test file will include a `setUp()` and `tearDown()` function. The setUp
|
||||
function can contain anything you would like to run before each test. The
|
||||
tearDown function can contain anything you would like to run after each test.
|
||||
Both functions accept no arguments and return nothing. You may leave either or
|
||||
both of these blank if you have no need for them. If you're using a compiler
|
||||
that is configured to make these functions optional, you may leave them off
|
||||
completely. Not sure? Give it a try. If you compiler complains that it can't
|
||||
find setUp or tearDown when it links, you'll know you need to at least include
|
||||
Next, a test file will include a `setUp()` and `tearDown()` function. The setUp
|
||||
function can contain anything you would like to run before each test. The
|
||||
tearDown function can contain anything you would like to run after each test.
|
||||
Both functions accept no arguments and return nothing. You may leave either or
|
||||
both of these blank if you have no need for them. If you're using a compiler
|
||||
that is configured to make these functions optional, you may leave them off
|
||||
completely. Not sure? Give it a try. If you compiler complains that it can't
|
||||
find setUp or tearDown when it links, you'll know you need to at least include
|
||||
an empty function for these.
|
||||
|
||||
The majority of the file will be a series of test functions. Test functions
|
||||
follow the convention of starting with the word "test" or "spec". You don't HAVE
|
||||
to name them this way, but it makes it clear what functions are tests for other
|
||||
developers. Test functions take no arguments and return nothing. All test
|
||||
The majority of the file will be a series of test functions. Test functions
|
||||
follow the convention of starting with the word "test" or "spec". You don't HAVE
|
||||
to name them this way, but it makes it clear what functions are tests for other
|
||||
developers. Test functions take no arguments and return nothing. All test
|
||||
accounting is handled internally in Unity.
|
||||
|
||||
Finally, at the bottom of your test file, you will write a `main()` function.
|
||||
This function will call `UNITY_BEGIN()`, then `RUN_TEST` for each test, and
|
||||
finally `UNITY_END()`.This is what will actually trigger each of those test
|
||||
functions to run, so it is important that each function gets its own `RUN_TEST`
|
||||
Finally, at the bottom of your test file, you will write a `main()` function.
|
||||
This function will call `UNITY_BEGIN()`, then `RUN_TEST` for each test, and
|
||||
finally `UNITY_END()`.This is what will actually trigger each of those test
|
||||
functions to run, so it is important that each function gets its own `RUN_TEST`
|
||||
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
|
||||
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.
|
||||
|
||||
When you're done, your test file will look something like this:
|
||||
When you're done, your test file will look something like this:
|
||||
|
||||
```C
|
||||
#include "unity.h"
|
||||
#include "file_to_test.h"
|
||||
|
||||
void setUp(void) {
|
||||
// set stuff up here
|
||||
}
|
||||
|
||||
void tearDown(void) {
|
||||
// clean stuff up here
|
||||
}
|
||||
|
||||
void test_function_should_doBlahAndBlah(void) {
|
||||
//test stuff
|
||||
}
|
||||
|
||||
void test_function_should_doAlsoDoBlah(void) {
|
||||
//more test stuff
|
||||
}
|
||||
|
||||
int main(void) {
|
||||
UNITY_BEGIN();
|
||||
RUN_TEST(test_function_should_doBlahAndBlah);
|
||||
RUN_TEST(test_function_should_doAlsoDoBlah);
|
||||
return UNITY_END();
|
||||
}
|
||||
#include "unity.h"
|
||||
#include "file_to_test.h"
|
||||
|
||||
void setUp(void) {
|
||||
// set stuff up here
|
||||
}
|
||||
|
||||
void tearDown(void) {
|
||||
// clean stuff up here
|
||||
}
|
||||
|
||||
void test_function_should_doBlahAndBlah(void) {
|
||||
//test stuff
|
||||
}
|
||||
|
||||
void test_function_should_doAlsoDoBlah(void) {
|
||||
//more test stuff
|
||||
}
|
||||
|
||||
int main(void) {
|
||||
UNITY_BEGIN();
|
||||
RUN_TEST(test_function_should_doBlahAndBlah);
|
||||
RUN_TEST(test_function_should_doAlsoDoBlah);
|
||||
return UNITY_END();
|
||||
}
|
||||
```
|
||||
|
||||
It's possible that you will require 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.
|
||||
It's possible that you will require 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.
|
||||
|
||||
|
||||
## How to Build and Run A Test File
|
||||
This is the single biggest challenge to picking up a new unit testing framework,
|
||||
at least in a language like C or C++. These languages are REALLY good at getting
|
||||
you "close to the metal" (why is the phrase metal? Wouldn't it be more accurate
|
||||
to say "close to the silicon"?). While this feature is usually a good thing, it
|
||||
|
||||
This is the single biggest challenge to picking up a new unit testing framework,
|
||||
at least in a language like C or C++. These languages are REALLY good at getting
|
||||
you "close to the metal" (why is the phrase metal? Wouldn't it be more accurate
|
||||
to say "close to the silicon"?). While this feature is usually a good thing, it
|
||||
can make testing more challenging.
|
||||
|
||||
You have two really good options for toolchains. Depending on where you're
|
||||
coming from, it might surprise you that neither of these options is running the
|
||||
You have two really good options for toolchains. Depending on where you're
|
||||
coming from, it might surprise you that neither of these options is running the
|
||||
unit tests on your hardware.
|
||||
There are many reasons for this, but here's a short version:
|
||||
- On hardware, you have too many constraints (processing power, memory, etc),
|
||||
@ -153,19 +170,19 @@ There are many reasons for this, but here's a short version:
|
||||
- On hardware, unit testing is more challenging,
|
||||
- Unit testing isn't System testing. Keep them separate.
|
||||
|
||||
Instead of running your tests on your actual hardware, most developers choose to
|
||||
develop them as native applications (using gcc or MSVC for example) or as
|
||||
applications running on a simulator. Either is a good option. Native apps have
|
||||
the advantages of being faster and easier to set up. Simulator apps have the
|
||||
advantage of working with the same compiler as your target application. The
|
||||
Instead of running your tests on your actual hardware, most developers choose to
|
||||
develop them as native applications (using gcc or MSVC for example) or as
|
||||
applications running on a simulator. Either is a good option. Native apps have
|
||||
the advantages of being faster and easier to set up. Simulator apps have the
|
||||
advantage of working with the same compiler as your target application. The
|
||||
options for configuring these are discussed in the configuration guide.
|
||||
|
||||
To get either to work, you might need to make a few changes to the file
|
||||
To get either to work, you might need to make a few changes to the file
|
||||
containing your register set (discussed later).
|
||||
|
||||
In either case, a test is built by linking unity, the test file, and the C
|
||||
file(s) being tested. These files create an executable which can be run as the
|
||||
test set for that module. Then, this process is repeated for the next test file.
|
||||
This flexibility of separating tests into individual executables allows us to
|
||||
much more thoroughly unit test our system and it keeps all the test code out of
|
||||
In either case, a test is built by linking unity, the test file, and the C
|
||||
file(s) being tested. These files create an executable which can be run as the
|
||||
test set for that module. Then, this process is repeated for the next test file.
|
||||
This flexibility of separating tests into individual executables allows us to
|
||||
much more thoroughly unit test our system and it keeps all the test code out of
|
||||
our final release!
|
||||
|
||||
Reference in New Issue
Block a user