The upcoming release of Isolator++ v5 marks a major shift in C++ unit testing, introducing a more intuitive and powerful API. We are moving from a MACRO-based API to a real API, making testing in C++ more flexible, developer-friendly, and consistent with modern C++ practices.
This blog highlights the key improvements in Isolator++ v5, explains why this transition matters, and provides examples comparing the old and new API to help developers quickly adapt.
Why Move from a MACRO-Based API to a Real API?
The previous MACRO-based API had several limitations that made C++ unit testing cumbersome:
- Readability Issues – MACROs often made tests harder to understand and debug.
- Limited Discoverability – Developers had to rely on documentation instead of benefiting from modern IDE features like IntelliSense and member discovery.
- Language Inconsistency – MACRO-based APIs don’t align well with modern C++ best practices.
- Scalability Problems – Adding new features required additional MACRO definitions, leading to complex code.
With Isolator++ v5, we are introducing a real API that makes testing more intuitive, flexible, and maintainable.
Key API Improvements in Isolator++ v5
Here’s how the new API improves the C++ unit testing experience:
🔹 Consistency: The new API follows the same design patterns as other existing Typemock APIs, ensuring a unified developer experience.
🔹 Language Consistency: The API aligns with standard C++ practices, making it easier for developers to integrate into their existing codebases.
🔹 Discoverability: The new API is self-explanatory. If a developer knows they want to mock a function, they can easily find the relevant method via IntelliSense without needing extensive documentation.
🔹 Explicitness: We designed the API to be as explicit as possible, reducing ambiguity and making it easier for developers to understand how to use it.
🔹 Single Point of Entry: All mocking starts from a single point (Isolator.Something()), improving clarity and usability.
🔹 Readability First: The new API prioritizes readability for test maintainers, ensuring that even developers who didn’t write the test can quickly understand what it does.
🔹 Single Way to Achieve Things: The API eliminates redundant methods, ensuring that there’s one clear way to perform each task.
🔹 Backwards Compatibility: We have minimized breaking changes to ensure that existing tests remain functional with minimal modifications. Including the old header will support the existing tests.
🔹 Pit of Success: The new defaults guide developers toward best testing practices, making it easier to write effective tests without extra effort.
Old API vs. New API: Code Comparison
Here’s a quick comparison of how the old MACRO-based API compares to the new API:
Old MACRO-Based API
|
1 2 3 4 5 6 7 8 9 10 |
TEST_F(MyTest, TestDependency) { FAKE_GLOBAL(SomeFunction); WHEN_CALLED(SomeFunction()).Return(42); int result = SomeFunction(); ASSERT_EQ(result, 42); ISOLATOR_CLEANUP(); } |
New API in Isolator++ v5
|
1 2 3 4 5 6 7 8 9 10 |
TEST_F(MyTest, TestDependency) { Isolator a; a.Testable.GlobalFunction(SomeFunctions); a.CallTo(SomeFunction()).WillReturn(42); int result = mock->SomeFunction(); ASSERT_EQ(result, 42); } |
🔹 Key Differences:
- The new API eliminates MACROs, making the syntax more explicit and readable.
- Mocking is now object-oriented, improving consistency and discoverability.
- No need to call ISOLATOR_CLEANUP after every test
- API explains what is happening. For example TestableGlobal – is used to fake global methods that linker might duplicate across many dlls’
How to Migrate from the MACRO-Based API to the New API
Migrating to the new API is straightforward. There is also an example ConvertVersion.ps to do most of the conversions.
1️⃣ Refactor use of variables. Locate local variables called ‘a’ and rename
2️⃣ Run Convert. Run the Convert to create a new directory with files that use the new API.
3️⃣ Refactor. Hand code the big API differences: WillDoInstead(), add template type to Variable.Get and changed default of a.Testable.GlobalFunction
4️⃣ Run and Validate Tests. Ensure that refactored tests produce the same expected results.
5️⃣ Leverage New API Features. Explore additional capabilities that weren’t possible with the old MACRO-based system.
Conclusion
Isolator++ v5 is a major leap forward for C++ unit testing. By moving from MACRO-based APIs to a real API, we’ve made unit testing easier, more flexible, and more aligned with modern C++ practices.
🚀 Isolator++ v5 is coming soon! Stay tuned for its release and be among the first to simplify your C++ testing process.
