Unresolved External Symbol errors while using Catch2

Question

I am trying to do Catch2 Unit Testing in Visual Studio. I have created a small test project to practice. When I try to compile this test project, I get a linker error. I am now trying to diagnose this linker error, but the Catch2.hpp header file contains thousands of lines of code. My hope is that someone who is more familiar with Catch2 or unit testing in general can diagnose what the issue is.

I will describe the process by which I created this project. I created a new project in a new solution. I have 4 files, all in the same directory, listed below.

The class I want to test:

//a.h

#pragma once

class A {
    friend int A_Tester_Func1(A a);
public:
    A(int num) : my_num_(num) {
    }
private:
    int my_num_;
};

The test:

//atester.cpp

#pragma once

#include "catch.hpp"
#include "a.h"

int A_Tester_Func1(A a) {
    return a.my_num_;
}

TEST_CASE("a contains a positive integer", "[a]") {
    //...
    A a(3);
    REQUIRE(A_Tester_Func1(a) == 3);

}

The main function that runs the tests:

//tester.cpp

#define CATCH_CONFIG_MAIN
#include "catch.hpp" // this should create the main function

The Catch2 Testing Framework:

// catch.hpp

/*
 *  Catch v2.13.2
 *  Generated: 2020-10-07 11:32:53.302017
*/

//~17-18k lines of code that from Catch2

#endif // TWOBLUECUBES_SINGLE_INCLUDE_CATCH_HPP_INCLUDED

When I try to compile this code in Visual Studio using the Local Windows Debugger button, I get a bunch of Unresolved External Symbol linker errors. I believe I read somewhere that Catch2 is "partially compiled." That may have something to do with it, but I don't know. Following this guide (StackOverflow: Best practices for Unit testing with Catch2 in Visual Studio) has worked for me, but I'm trying to understand why the small example above is not successfully linking.

I have included the linker errors below for completeness, although I feel that they will probably not be necessary for the question.

1>atester.obj : error LNK2019: unresolved external symbol "public: __thiscall Catch::StringRef::StringRef(char const *)" (??0StringRef@Catch@@QAE@PBD@Z) referenced in function "public: class Catch::BinaryExpr<int const &,int const &> const __thiscall Catch::ExprLhs<int const &>::operator==<int>(int const &)" (??$?8H@?$ExprLhs@ABH@Catch@@QAE?BV?$BinaryExpr@ABHABH@1@ABH@Z)
1>atester.obj : error LNK2019: unresolved external symbol "struct Catch::ITestInvoker * __cdecl Catch::makeTestInvoker(void (__cdecl*)(void))" (?makeTestInvoker@Catch@@YAPAUITestInvoker@1@P6AXXZ@Z) referenced in function "void __cdecl `anonymous namespace'::`dynamic initializer for 'autoRegistrar1''(void)" (??__EautoRegistrar1@?A0xf9ca9c7d@@YAXXZ)
1>atester.obj : error LNK2019: unresolved external symbol "public: __thiscall Catch::NameAndTags::NameAndTags(class Catch::StringRef const &,class Catch::StringRef const &)" (??0NameAndTags@Catch@@QAE@ABVStringRef@1@0@Z) referenced in function "void __cdecl `anonymous namespace'::`dynamic initializer for 'autoRegistrar1''(void)" (??__EautoRegistrar1@?A0xf9ca9c7d@@YAXXZ)
1>atester.obj : error LNK2019: unresolved external symbol "public: __thiscall Catch::AutoReg::AutoReg(struct Catch::ITestInvoker *,struct Catch::SourceLineInfo const &,class Catch::StringRef const &,struct Catch::NameAndTags const &)" (??0AutoReg@Catch@@QAE@PAUITestInvoker@1@ABUSourceLineInfo@1@ABVStringRef@1@ABUNameAndTags@1@@Z) referenced in function "void __cdecl `anonymous namespace'::`dynamic initializer for 'autoRegistrar1''(void)" (??__EautoRegistrar1@?A0xf9ca9c7d@@YAXXZ)
1>atester.obj : error LNK2019: unresolved external symbol "public: virtual __thiscall Catch::AutoReg::~AutoReg(void)" (??1AutoReg@Catch@@UAE@XZ) referenced in function "void __cdecl `anonymous namespace'::`dynamic atexit destructor for 'autoRegistrar1''(void)" (??__FautoRegistrar1@?A0xf9ca9c7d@@YAXXZ)
1>atester.obj : error LNK2019: unresolved external symbol "public: static class std::basic_string<char,struct std::char_traits<char>,class std::allocator<char> > __cdecl Catch::StringMaker<int,void>::convert(int)" (?convert@?$StringMaker@HX@Catch@@SA?AV?$basic_string@DU?$char_traits@D@std@@V?$allocator@D@2@@std@@H@Z) referenced in function "class std::basic_string<char,struct std::char_traits<char>,class std::allocator<char> > __cdecl Catch::Detail::stringify<int>(int const &)" (??$stringify@H@Detail@Catch@@YA?AV?$basic_string@DU?$char_traits@D@std@@V?$allocator@D@2@@std@@ABH@Z)
1>atester.obj : error LNK2019: unresolved external symbol "public: virtual __thiscall Catch::ITransientExpression::~ITransientExpression(void)" (??1ITransientExpression@Catch@@UAE@XZ) referenced in function "public: virtual __thiscall Catch::BinaryExpr<int const &,int const &>::~BinaryExpr<int const &,int const &>(void)" (??1?$BinaryExpr@ABHABH@Catch@@UAE@XZ)
1>atester.obj : error LNK2019: unresolved external symbol "void __cdecl Catch::formatReconstructedExpression(class std::basic_ostream<char,struct std::char_traits<char> > &,class std::basic_string<char,struct std::char_traits<char>,class std::allocator<char> > const &,class Catch::StringRef,class std::basic_string<char,struct std::char_traits<char>,class std::allocator<char> > const &)" (?formatReconstructedExpression@Catch@@YAXAAV?$basic_ostream@DU?$char_traits@D@std@@@std@@ABV?$basic_string@DU?$char_traits@D@std@@V?$allocator@D@2@@3@VStringRef@1@1@Z) referenced in function "private: virtual void __thiscall Catch::BinaryExpr<int const &,int const &>::streamReconstructedExpression(class std::basic_ostream<char,struct std::char_traits<char> > &)const " (?streamReconstructedExpression@?$BinaryExpr@ABHABH@Catch@@EBEXAAV?$basic_ostream@DU?$char_traits@D@std@@@std@@@Z)
1>atester.obj : error LNK2019: unresolved external symbol "public: __thiscall Catch::AssertionHandler::AssertionHandler(class Catch::StringRef const &,struct Catch::SourceLineInfo const &,class Catch::StringRef,enum Catch::ResultDisposition::Flags)" (??0AssertionHandler@Catch@@QAE@ABVStringRef@1@ABUSourceLineInfo@1@V21@W4Flags@ResultDisposition@1@@Z) referenced in function "void __cdecl ____C_A_T_C_H____T_E_S_T____0(void)" (?____C_A_T_C_H____T_E_S_T____0@@YAXXZ)
1>atester.obj : error LNK2019: unresolved external symbol "public: void __thiscall Catch::AssertionHandler::handleExpr(struct Catch::ITransientExpression const &)" (?handleExpr@AssertionHandler@Catch@@QAEXABUITransientExpression@2@@Z) referenced in function "void __cdecl ____C_A_T_C_H____T_E_S_T____0(void)" (?____C_A_T_C_H____T_E_S_T____0@@YAXXZ)
1>atester.obj : error LNK2019: unresolved external symbol "public: void __thiscall Catch::AssertionHandler::handleUnexpectedInflightException(void)" (?handleUnexpectedInflightException@AssertionHandler@Catch@@QAEXXZ) referenced in function __catch$?____C_A_T_C_H____T_E_S_T____0@@YAXXZ$0
1>atester.obj : error LNK2019: unresolved external symbol "public: void __thiscall Catch::AssertionHandler::complete(void)" (?complete@AssertionHandler@Catch@@QAEXXZ) referenced in function __catch$?____C_A_T_C_H____T_E_S_T____0@@YAXXZ$0
1>MSVCRTD.lib(exe_main.obj) : error LNK2019: unresolved external symbol _main referenced in function "int __cdecl invoke_main(void)" (?invoke_main@@YAHXZ)

What is causing these errors? How do I fix these errors while keeping catch.hpp in the same project as my source files?

Wasteful

I assume you have a problem with the catch.hpp file you are using, because i just tried your setup on vstudio 2022 with my catch.hpp and it worked out of the box. try my file github.com/mickeyperlstein/working_catch2_testing/blob/master/… maybe thats your issue – Aglow

Answer 1

In a .cpp file, add this to make the project a Catch2 test runner:

#define CATCH_CONFIG_RUNNER
#include "catch.hpp"

Read more at Supplying main() yourself

Percival

This doesn't answer the question. – Wasteful

Ah, sorry, I see now that you already had #define CATCH_CONFIG_MAIN. If that was missing, then I think it would cause the exact same errors. Perhaps the #define CATCH_CONFIG_MAIN is not in exactly one place or not in the correct place in your project. – Percival

my solution was to move the catch2 tests to a separate project and compile my main project as a static library. I'm not sure if that is necessary (which is what the question is about), but it worked. – Wasteful

We have all our Catch2 tests in our application's executable project. So I know that can work fine. Not sure if that's the best practice though. I think I would prefer having them in a separate project, but then you might have to expose an API just for testing. – Percival

Answer 2

I ran into the same problem.

You need to keep #define CATCH_CONFIG_MAIN in the first line of the file, especially before other #include.

Gusher

Answer 3

1. atester.cpp must not have the #pragma once directive. It's for header files, and while it may not be your source of trouble, it simply doesn't belong. Since you're not providing enough detail (namely: where's the minimized project file?), I have to be conservative here.

2. It seems that tester.cpp is not part of the project that you're building. Just because it's a file that exists on disk doesn't mean it's automatically picked up. You have to manually add it to the MSVC project. That's all there's to it. I use Catch2 with MSVS all the time and that's all it takes to make it work.

Plume

Answer 4

If anyone else has a similar problem in the future, make sure you're including catch_amalgamated.cpp your project.

Both catch_amalgamated.hpp and catch_amalgamated.cpp should be included in your project in order for it to link properly.

A sample working Visual Studio solution would have the following structure:

SolutionDir/
    solution.sln
    ProjectDir/
        catch_amalgamated.cpp
        catch_amalgamated.hpp
        main.cpp
        sample_test_suite.cpp
        project.vcxproj
        ...

Contents of main.cpp:

#define CATCH_CONFIG_MAIN
#include "catch_amalgamated.hpp"

Contents of sample_test.cpp

#include "catch_amalgamated.hpp"

unsigned int Factorial( unsigned int number ) {
    return number <= 1 ? number : Factorial(number-1)*number;
}

TEST_CASE( "Factorials are computed", "[factorial]" ) {
    REQUIRE( Factorial(1) == 1 );
    REQUIRE( Factorial(2) == 2 );
    REQUIRE( Factorial(3) == 6 );
    REQUIRE( Factorial(10) == 3628800 );
}

Wayne