Learn how to use Ceedling to test your embedded software
Ceedling is a great tool for C that makes it easier to unit test your embedded software. It'll make it easy to run and execute tests and will automatically generate mocks for you.
Ceedling saves you the time required to hand-edit boilerplate unit test code and the time to set up your own test build system (no messing with Makefiles!).
The only problem is that it's not so obvious how to use Ceedling or how it works. Yes there is documentation, but Ceedling is very flexible and has a lot of options. What you really want to know is how to start using it on your project.
The e-book A Field Manual for Ceedling: How to Unit Test Embedded Software (in C) will show you how to install Ceedling, how to easily create and run tests, how to create and use mocks, and how to customize Ceedling by changing settings. It'll also explain what you need to know about how Ceedling works so that you can use it more effectively.
Learn what you need to know to use Ceedling effectively
Inside you'll find these chapters:
Learn how to install Ceedling on to your computer and into your project -- including how to structure your project tree for the best results.
Creating Modules and Running tests
Learn how to use Ceedling's module generator to easily create source and test files and avoid writing boiler plate code. Also learn how to operate Ceedling from the command line, including the different ways to run your tests.
Learn how to write tests (including tests with mocks) and create your own test files without the module generator.
Testing with Unity
Learn about how to use the Unity unit test framework in your tests and how to test a variety of different data types.
Mocking with CMock
Learn what mocks are, how to create them automatically with Ceedling, and how to use them in your tests -- in a variety of situations.
How Ceedling Knows What to Test
Learn how Ceedling builds and runs each test and how it decides what to include in each. This understanding of how Ceedling works will help you use it more effectively.
Changing the Configuration
Learn how to change and add settings in the configuration files to customize Ceedling for your project.
For even more detail, check out the entire table of contents.
Run on the host for maximum efficiency
All of this is designed to get you set up to test your embedded code on your host computer... not on the target. For speed and simplicity you want to unit test your code on the host -- and that's what this book explains.
The book uses many code examples to explain it all. The examples are all in the book, but if you download the package including the code examples you'll also get all of the source code. These are real Ceedling projects where you can run the tests yourself.
At 94 pages, the book covers the important things that you need to know but won't overwhelm you with too much information.
What is it... a reference manual?
No, I wouldn't call it a reference manual, as it doesn't cover everything you can do with Ceedling -- or handle every scenario you might encounter. This book is my attempt to explain to you the way I have used Ceedling (successfully!) to unit test my embedded software applications.
Who is this book for?
This book might be good for you if:
- You've never written any unit tests and don't know where to begin.
- You have written unit tests (maybe even using Unity or CMock), but they were difficult to set up and run. You need a better way to do this.
- You've actually used Ceedling with some success, but want to know more about how it works and how to configure it.
What isn't in the book?
There's plenty of stuff that's not in this book. For example, don't get the book if you want to learn any of these things:
- How to integrate Ceedling with your IDE. This book explains how to use Ceedling from the command line alongside of your IDE.
- How to do test-driven development. This book will show you how to construct unit tests and run them. This is a stepping stone to TDD.
- How to test on the target. Testing on the target is slow and complicated to set up. Testing on your host computer is preferable for speed and simplicity -- especially for unit tests.
- How to test on a host-based simulator. While this can be done (if a simulator is available), it's complicated to set up.
If you need it, I can help you with these sorts of things on a case-by-case basis. Just shoot me an email and let me know what you need.
So, why Ceedling?
Oh, there are a bunch of C "unit test frameworks" floating around, but they're not all the same. Some will need a lot more work to set up and maintain than others. Which one should you pick, and how do you actually start using it on your project?
A few years ago, I didn't write any unit tests.
I had heard about software unit testing, but I didn't quite understand how I could use it in my embedded software. Then when I actually worked on a few projects with existing unit tests, I started to get it. I could see how the tests were used to exercise the code, and I could write my own tests to verify that my code did exactly what I wanted.
But these weren't embedded projects, and they weren't written in C. These other projects were developed in Visual Studio and Android Studio, where unit test support is built in. You can quickly add and run unit tests automatically. You just write the test code, and tell the IDE to run the tests. You don't have to add any boilerplate code or go through a bunch of manual steps. Running the tests is easy.
And easy is what you really want... especially when you're just starting out. You don't want to get waste time trying to figure out (or build) the test infrastructure, you just want it to work -- so you can start writing as many tests as quickly as possible.
But how can we get this same sort of unit-test magic for our embedded applications written in C?
The answer is the open-source test framework called Ceedling.
Ceedling makes creating and running unit tests for your embedded projects easy and automatic. It will automatically find and run your tests with a simple command -- just like those fancy IDEs -- except nice and cleanly at the command line.
Ceedling also makes it easy to test the interactions between software units with mocks. This is especially difficult in C, and requires a bit of build infrastructure to make it happen. But Ceedling can automatically create mocks in each of your unit tests. This is especially important for embedded software because you can use mocks to simulate hardware.
Because of how it can automatically generate mocks, Ceedling is really more than just a "unit test framework." It's a complete build and test system.
With Ceedling, it's easier to create and maintain a suite of tests for your embedded software.
There's still one problem though. While Ceedling is great, how to use it is not always obvious. Yes, there is documentation. But Ceedling is really flexible, so there are a lot of options. It's just not always clear what you need to do to solve your particular problem.
How do you add it to an existing project? How do you test different groups of files, and how do you actually use mocks? How do you configure it with different options?
All of these things are possible... and you can learn how in my e-book: A Field Manual for Ceedling: How to Unit Test Embedded Software (in C).