Ceedling in Eclipse

Or "Unity in Eclipse" or "CMock in Eclipse" or maybe even hints about "Ceedling in some other IDE". Often the concepts are the same. The point is that you want to make your life convenient by pulling your testing toolchain into your IDE.

Well, you've come to the right place.

Your test tools are command line tools by nature. Luckily, most modern IDE's are designed to launch command line tools in the background and gather results from them. The goal is to make this as seemless as possible. TO accomplish this, we're going to cover a few areas:

  • Setting Up the Project
  • Triggering Tests From the IDE
  • Viewing Results, Particularly Failures
  • Making your Test and Source Modules Feel Related
  • Handy Code Completion

Before we get going on the details, download and install both Ceedling and the latest version of Eclipse. You may need to update your Java environment if it's behind (If you're on a Mac and it's complaining about your version of Java despite having a newer version, you'll want to install the latest 64-bit JDK and Eclipse will stop complaining.).

Installing Required Plugins

We will be making use of Eclipse's optional C/C++ Unit Testing support. First, make sure you have CDT (The C/C++ Development Toolkit) installed in Eclipse. Then you will also want to install the optional CDT Unit Testing Framework. You can do this by going to Install New Software, enter unit in the filter box and select C/C++ unit testing support.

Setting Up Your Project

You can create a new project or work with an existing project that is managed by Ceedling. There is no reason that it has to be in the "Workspace" directory of Eclipse. Launch Eclipse.

Select New Project (either from the New menu or by right-clicking the Project Explorer and selecting Add Project...). This will bring up a dialog box. Expland the section for C/C++ and select Makefile Project with Existing Code. Press Next.

Name the project whatever you like. In the Existing Code Location field, enter or browse to the folder containing your Ceedling-Managed project. For Toolchain For Indexer Settings, select any local gcc version that builds natively. This will help your project automatically index its files. If none are present, you may choose <NONE>. This last step will keep it from making too many incorrect assumptions about how we want to work. Press Finish.

Triggering Tests from the IDE

Next we want to actually trigger tests from the IDE. To do this, we want to tell our IDE that we want to use some Run As Configurations to use with ceedling and what targets are available.

Let's start by adding the default option. Long-Click the Run As button and select Run Configurations.... On the navigation tree, select C/C++ Unit and Add a new configuration. Name it All Tests.

The Main tab of your new configuration allows you to enter the location of your C/C++ application. We're going to be calling Ceedling, like so: ~/.rvm/gems/ruby-2.0.0-p643/gems/ceedling-0.19.0/bin/ceedling (or whereever your copy of ceedling is). On this tab you are also going to want to select Disable Auto Build, because there is no need to build anything in particular before calling ceedling.

Next, on the Arguments tab, add arguments clobber on one line and test:all on the next. You will be using the default working directory.

On the C\C++ Testing tab, select Google Tests Runner as the Test Runner. I know... it's sad that there is no support for Unity directly, yet... but luckily Ceedling is already good at pretending to be Google Test... good enough that Eclipse shouldn't notice the difference. We just have to enable it. Open your Ceedling project.yml file. Scroll down until you see the section marked plugins and add the following plugin. You should comment out all other display plugins, like pretty-print:

:plugins:
    :enabled:
        #- stdout_pretty_tests_report
        - stdout_gtestlike_tests_report

Back in Eclipse, on the Environment tab, Add an environment variable. Name it TERM and assign it a value of xterm.

The rest of the tabs are probably fine with defaults, so you can select Apply to finish this particular Run Configuration.

So that's useful... but what if we want to test just a single module? Let's do that quick. Right-Click on the All Tests item and select Duplicate. We're going to name this one Test This. On the Arguments tab, update the list to just one item: test:${selected_resource_name} instead. Again press Apply. Press OK.

You can now verify that your new target works. Selecting All Tests from the menu should kick off all your tests. When finished, it should show you the results in a C\C++ Unit View. Clicking any particular test will show its details (if any). Double-clicking the details of a failure should automatically bring you to that test!

Running This Test is slightly more tricky than it should be. You need to make sure your editor window is selected and that you are viewing either the test file, it's related source module, or the header for that source module. If you then select This Test, it should kick off the test just for that.

This is a feature that would desperately like a hot-key. Unfortunately it appears that Eclipse does not provide a stub for a hot-key for Run As _. The closest thing I found was Run Configuration which seems to be Ctrl+Alt+R by default (Cmd+Alt+R for Mac users). This shows the configuration window. You can then use the arrow keys to select the one you want and then press ENTER.

NOTE: If you are on a Mac and when you run your tests, and it complains about character encoding, this may be due to a quirk in how Eclipse launches from the Finder. Launch it once from the command line, and it should fix itself from there. See this bug for reference.

Viewing Results, Particularly Failures

The C\C++ Unit View shows all the results automatically when the tests were run. It shows them as a tree that you can expand or collapse as desired. Clicking on a test will show any details for that test (not likely to have any for a passing test). If you double-click the details for a failure, it will bring you to the actual failing test if your paths are all correct.

This tip comes from mad scientist Oscar Edvardsson, a man who is a helpful participant on our forums and github page. He discovered that we can use the MoreUnit plugin to get some added convenience. Start by installing it by opening your Eclipse Marketplace under your Help menu. Search for MoreUnit and install it. Make sure that MoreUnit Light is checked as you do so.

Once installed, open your project properties (right click the project and select Properties). and navigate to MoreUnit->User Languages.

Enable Use project specific settings and fill in the rules. For example, a common Ceedling configuration would be to have ${srcProject}/src for the source path, ${srcProject}/test for the test path, and test_${srcFile} or Test${srcFile} for naming the test file. Select Save.

Now, whenever you have a source or test file open, you should be able to click ctrl+J to jump to the other. If the file doesn't exist, it will offer to make it for you.

Unfortunately, we haven't figured out a way to make it handle your header file as well, but MOST of your flow is between the source and test files, so this is still incredibly helpful.

Handy Code Completion

There are a lot of little tweaks you can do to make your experience developing your test code in Eclipse more efficient.

First, let's set up code templates for common tasks (like creating a test). We start by opening Preferences → C/C++ → Editor → Templates.

From there, we add a template by clicking New, and then filling out the details. Let's start with a template for adding a test. We select New and then enter test for the Name. We select C\C++ for the Context and check the box to let Eclipse know we want to Automatically Insert our code. We add something helpful to the Description like add a skeleton for testing a function. Finally, under Pattern, we get to add the actual template. Ours might look something like this:

void test_${function_name}_Should_${should}(void)
{
    ${line_selection}${cursor}
     
    ${function_name}();
}

There are a couple of things to note. One is that we made up some custom fields to use. These are going to allow the user to tab between them and enter data. Fields that are named the same thing will be filled out automatically when the first one is entered. The curser field is special to Eclipse and will be where the cursor leaves off when they finish tab completing. We have chosen to let them start typing inside our brackets.

To use a template, type the start of the template name test then hit your hot key combination for autocomplete (default Ctrl+Space). You can then tab between fields and fill them out.

Let's make one more. This time, we'll make a test which we don't plan to fill out right now... instead it'll be one we plan to ignore.

void test_${function_name}_Should_BeCompleted(void)
{
    TEST_IGNORE_MESSAGE("${function_name} Needs Definition.");
}

So what happens if we want to create an entire file instead? No problem! For this, we use Eclipse's support for launching external tools. We click the External Tool Confgurations... option, then press the add button to create a new tool. We can name it something like Create Module. On the Main tab, put the usual location for ceedling, just like you did in the Run Configurations... above. The Arguments box receives a single argument that uses this built-in Eclipse feature to launch a prompt to ask for the module name:

module:create[${string_prompt:new_module_name:Module}]

Now, when you double-click the external tool (or use a hotkey to launch it), you will be prompted for a module name. Type one in (maybe something like Snow) and then press enter. The script is called and the script creates a src/Snow.c, src/Snow.h, and test/TestSnow.c, all in the appropriate folders. Feel free to add different variations for different folders and/or templates.

This setup can also be used with ceedling module:destroy[] to have it remove files... though you want to be careful about making it TOO easy to call that!

Finishing Touches

Finally, when we're using Eclipse's built-in autocomplete and jump-to-definition, it gets very obnoxious for it to jump to our mocks when clearly we wanted the real file. Most often, you'll want to block the mocks directory from being indexed... or likely all the build directories.

You can ignore them by right-clicking the mocks folder (or the build folder) and select Exclude From Build. Once you have excluded all desired folders, you can right-click the project itself and select Index -> Freshen All Files to force it to reindex.

Good Luck!

Hopefully this was a useful jaunt through some of Eclipse's settings... perhaps more useful, though, is knowing what kinds of things you can do to customize your experience... we hope this leads to a better experience in whatever environment you are using.

Happy Testing!