Carbon

You can’t unit test C, right?

Carbon helps you write better C/C++ tests. 🙂

Carbon is a testing framework that focuses on being lightweight and straightforward, giving the best possible development experience. Whether you work on GNU/Linux, BSDs, Windows or macOS, if you write C/C++ code, Carbon can help you.

Carbon is free software: you can redistribute it and/or modify it under the terms of the BSD 3-Clause “New” or “Revised” License as published by The Regents of the University of California.
Carbon is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the BSD 3-Clause “New” or “Revised” License for more details.
You should have received a copy of the BSD 3-Clause “New” or “Revised” License along with Carbon. If not, see https://opensource.org/license/BSD-3-Clause.

Table of Contents

• Usage
  • Target code
  • Test case
  • Entrypoint
  • Execution
• Code coverage

Usage

(…)

git submodule add /~https://github.com/sparky-game/carbon vendor/carbon

(…)

Target code

// x.h

#pragma once

void inc_int(int *x);

// x.c

#include "x.h"

void inc_int(int *x) {
  ++(*x);
}

(…)

Test case

// x_test.c

#include <carbon.h>
#include "x.h"

CARBON_TEST(x, inc_int) {
  int a = 1, b = 0;
  carbon_should_not_be(a, b);
  inc_int(&b);
  carbon_should_be(a, b);
  return CARBON_OK;
}

(…)

Entrypoint

// carbon.c

#define CARBON_IMPLEMENTATION
#include <carbon.h>

int main(void) {
  return CARBON_RUN_ALL();
}

(…)

cc -I vendor/carbon -std=c99 x.c x_test.c carbon.c -o carbon

Execution

(…)

$ ./carbon -h
usage: ./test/carbon [OPTION]
Options:
  -o, --output     output JUnit XML test results to specific file (default: `carbon_results.xml`)
  -h, --help       display this help and exit
  -v, --version    output version information and exit

Report bugs to: </~https://github.com/sparky-game/carbon/issues>
BSD Carbon home page: </~https://github.com/sparky-game/carbon>

(…)

Additionally, it will create a file named carbon_results.xml with the execution results formatted as JUnit XML.

Code coverage

Code or test coverage is a metric which measures the amount of source code getting executed when a test suite is run. It’s important to mention that this measurement doesn’t relate by any means to the quality of the codebase, it just reflects how complete and thorough a specific test suite is, nothing more.

Nevertheless, it’s a nice metric to have, and it’s important that Carbon supports it. As we’re working with C/C++, the most used tool for the job is gcov. When using the --coverage flag, it passes to the compiler/linker specific flags to produce certain code instrumentation.

• The *.gcno notes files are generated when the source files are compiled with the -ftest-coverage option (contained inside the --coverage flag). It contains information to reconstruct the basic block graphs and assign soure line numbers to blocks.
• The *.gcda count data files are generated when a program linked with -lgcov option (contained inside the --coverage flag) containing object files built with the -fprofile-arcs option (contained inside the --coverage flag) is executed. It contains arc transition counts, value profile counts and some summary information.

They shouldn’t be accessed manually, but with gcov itself, using one of its formatting options, e.g. --json-format.