summaryrefslogtreecommitdiff
path: root/test/vendor/ceedling/docs/UnityGettingStartedGuide.md
diff options
context:
space:
mode:
Diffstat (limited to 'test/vendor/ceedling/docs/UnityGettingStartedGuide.md')
-rw-r--r--test/vendor/ceedling/docs/UnityGettingStartedGuide.md192
1 files changed, 0 insertions, 192 deletions
diff --git a/test/vendor/ceedling/docs/UnityGettingStartedGuide.md b/test/vendor/ceedling/docs/UnityGettingStartedGuide.md
deleted file mode 100644
index 5e4427ce9..000000000
--- a/test/vendor/ceedling/docs/UnityGettingStartedGuide.md
+++ /dev/null
@@ -1,192 +0,0 @@
-# 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
-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
-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
-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
-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
-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
-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
-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
-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
-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
-overview of everything in the project.
-
-- `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
-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
-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
-everything is configured properly.
-- `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
-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
-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. Also, the automated scripts that come with Unity or Ceedling will default
-to looking for test functions to be prefixed this way. 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`
-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.
-
-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();
-}
-```
-
-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.
-
-
-## 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
-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
-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),
-- On hardware, you don't have complete control over all registers,
-- 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
-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
-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
-our final release!
-
-
-*Find The Latest of This And More at [ThrowTheSwitch.org](https://throwtheswitch.org)*