git:20260724.d4db756 to git:20260725.09af35b

---

name: googletest-embedded-arm

description: "Author and run GoogleTest 1.17+ for embedded C++ on ARM targets - TEST() / TEST_F() / TEST_P() / TYPED_TEST(), EXPECT_* vs ASSERT_* assertions, fixtures with SetUp() / TearDown(), value-parameterised tests, GoogleMock when paired, cross-compile with arm-none-eabi-g++, run on host or under QEMU via the qemu-system-test-runner skill, --gtest_filter / --gtest_output=xml:results.xml / --gtest_shuffle / --gtest_repeat command-line flags, and XML / JSON output parsing for CI. Use when the unit-under-test is C++ (modern C++17+) and the team wants the de-facto C++ test framework instead of the C-only Unity. For C use unity-test-framework-c; for pure mocks use cmock-reference."

metadata:

keywords: "googletest, gtest, gmock, embedded, arm, c++, cortex-m, cortex-a"

---

# googletest-embedded-arm

## Overview

GoogleTest is, per the README at

[github.com/google/googletest](https://github.com/google/googletest),

"Google's C++ test framework" - an xUnit-style framework merged

with GoogleMock so the two ship together. The 1.17.x branch

"requires at least C++17". For embedded ARM use, the framework

runs anywhere a hosted C++ standard library is available - on

the host, under QEMU, and on Cortex-A Linux targets; for

Cortex-M without an OS, a minimal `_write` / `_exit` semihosting

stub is the bridge.

This skill wraps GoogleTest for embedded C++ work. Composes

with:

- `embedded-coverage-strategy-reference`

for gcov / llvm-cov instrumentation.

- `qemu-system-test-runner`

for running the binary on a virtual Cortex-M / Cortex-A.

- For pure-C suites, prefer

`unity-test-framework-c`;

for mock-heavy suites prefer the Ceedling stack via

`cmock-reference`.

## When to use

- Unit-under-test is **C++** (not C). For C, use

`unity-test-framework-c`.

- Target is **Cortex-A running Linux** or **Cortex-M with semihosting** - anything with enough RAM for the gtest binary (~300 KB stripped).

- Team wants the **de-facto C++ framework** with rich matchers

(GoogleMock, value-parameterised tests, typed tests).

- The build pipeline can run a host build for speed and a

cross-compile under QEMU for architecture sanity.

## Authoring

### Minimal test

Per [google.github.io/googletest/primer.html](https://google.github.io/googletest/primer.html):

```cpp

#include <gtest/gtest.h>

#include "ringbuffer.h"

TEST(RingbufferTest, EmptyOnInit) {

Ringbuffer<int, 8> rb;

EXPECT_TRUE(rb.empty());

EXPECT_EQ(0u, rb.size());

}

TEST(RingbufferTest, PushIncrementsSize) {

Ringbuffer<int, 8> rb;

rb.push(42);

EXPECT_EQ(1u, rb.size());

EXPECT_FALSE(rb.empty());

}

```

`TEST(SuiteName, TestName)` registers an independent test; the

first argument is "the name of the test suite, and the second

argument is the test's name within the test suite" (Primer doc).

### Fixtures (TEST_F)

When several tests share setup, derive from `::testing::Test`:

```cpp

class RingbufferTest : public ::testing::Test {

protected:

void SetUp() override { rb.clear(); }

void TearDown() override { /* nothing */ }

Ringbuffer<int, 8> rb;

};

TEST_F(RingbufferTest, PopReturnsPushedValue) {

rb.push(7);

int v = 0;

EXPECT_TRUE(rb.pop(&v));

EXPECT_EQ(7, v);

}

```

Per the Primer: "GoogleTest does not reuse the same test fixture

for multiple tests" - each `TEST_F` gets a fresh instance.

### Fatal vs non-fatal

| Family | On failure | Use when |

|---|---|---|

| `EXPECT_*` (e.g. `EXPECT_EQ`) | Records failure; continues | Each assertion is independent; collect all failures |

| `ASSERT_*` (e.g. `ASSERT_EQ`) | Records failure; **aborts current function** | Subsequent assertions would crash (e.g. null pointer deref) |

Per the Primer: "Usually EXPECT_* are preferred, as they allow

more than one failure to be reported in a test." Use `ASSERT_*`

only when the next line would dereference a possibly-null pointer

returned from the previous check.

```bash

```

```bash

-kernel ringbuffer_test.elf

```

| Flag | Effect |

|---|---|

## Anti-patterns

| Anti-pattern | Why it fails | Fix |

|---|---|---|

| `ASSERT_EQ` then ignore the abort and continue | Subsequent assertions undefined; can crash | Use `EXPECT_EQ` unless next line dereferences the value |

| `GTEST_HAS_PTHREAD=1` on bare-metal Cortex-M | Link fails: pthread symbols missing | Always `-DGTEST_HAS_PTHREAD=0` on M-profile cross-builds |

| Death tests on bare-metal | No `fork()`; test hangs or aborts oddly | Skip death tests on M-profile; or use `--gtest_filter=-*DeathTest*` |

| Linking `gtest` without `gtest_main` then no own `main` | "undefined reference to main" | Link `gtest_main` or write `int main(int argc, char **argv) { testing::InitGoogleTest(&argc, argv); return RUN_ALL_TESTS(); }` |

| Test order dependence | `--gtest_shuffle` reveals; CI breaks intermittently | Each `TEST_F` must work in any order; reset state in `SetUp` |

| Optimised coverage build | `-O2` collapses branches gcov can't see | `-O0 -g` for the coverage build per coverage-reference skill |

| `TEST_P` without `INSTANTIATE_TEST_SUITE_P` | Compiles but never runs | Always pair |

| Mocking everything | Tests measure mocks not behaviour | Mock at the I/O boundary only - see `cmock-reference` |

## Limitations

- **C++ only.** For pure C suites use

`unity-test-framework-c`.

- **Heap required.** GoogleTest allocates internally; ultra-low-

RAM Cortex-M0 (8 - 16 KB) may not have headroom. Use Unity for

those targets.

- **No native parameterised test = different test names.** Each

`TEST_P` instance is `Boundaries/WrapTest.WrapAtCapacity/4` -

the `/4` is the param index, not the value. Use

`INSTANTIATE_TEST_SUITE_P(..., ::testing::PrintToStringParamName())`

to encode the value into the name.

- **Death tests require `fork()`** - not available on bare-metal

or under most RTOSes. Per the Advanced Guide they run "in

separate child processes".

- **No determinism guarantee with `--gtest_shuffle`** - the seed

is logged but rerunning with the same seed and a code change

produces a different schedule.

- **GoogleMock pulls in `std::function`-based call recording** -

on cross-compiles with `-fno-exceptions` you may need

`-DGTEST_HAS_EXCEPTIONS=0` to compile cleanly.

## References

Cited inline. Foundational documents:

- GoogleTest README - [github.com/google/googletest](https://github.com/google/googletest).

- GoogleTest Primer - [google.github.io/googletest/primer.html](https://google.github.io/googletest/primer.html).

- GoogleTest Advanced Guide - [google.github.io/googletest/advanced.html](https://google.github.io/googletest/advanced.html).

- ARM GNU Toolchain - [developer.arm.com Tools and Software / GNU Toolchain](https://developer.arm.com/Tools%20and%20Software/GNU%20Toolchain).

- Sibling skills:

`unity-test-framework-c`,

`ceedling-build-runner`,

`cmock-reference`,

`qemu-system-test-runner`,

`embedded-coverage-strategy-reference`,

`hardware-in-loop-reference`.