[thirdparty/squid.git] / src / tests / STUB.h

/*
 * Copyright (C) 1996-2025 The Squid Software Foundation and contributors
 *
 * Squid software is distributed under GPLv2+ license and includes
 * contributions from numerous individuals and organizations.
 * Please see the COPYING and CONTRIBUTORS files for details.
 */

#ifndef SQUID_SRC_TESTS_STUB_H
#define SQUID_SRC_TESTS_STUB_H

/** \group STUB
 *
 *  A set of useful macros to create stub_* files.
 *
 * Intended for use building unit tests, if a stubbed function is called
 * by any code it is linked to it will abort with a message indicating
 * which API file is missing from the linked dependencies.
 *
 * Usage:
 *    at the top of your intended stub file define STUB_API to be the
 *    name of the .cc file or library you are providing a stub of
 *    then include this STUB.h header.
 *
 *   #define STUB_API "foo/libexample.la"
 *   #include "tests/STUB.h"
 */
#include <iostream>

// Internal Special: the STUB framework requires this function
#define stub_fatal(m) { std::cerr<<"FATAL: "<<(m)<<" for use of "<<__func__<<"\n"; exit(EXIT_FAILURE); }

/// macro to stub a void function.
#define STUB { stub_fatal(STUB_API " required"); }

/// macro to stub a void function without a fatal message
/// Intended for registration pattern APIs where the function result does not matter to the test
#define STUB_NOP { std::cerr<<"SKIP: "<<STUB_API<<" "<<__func__<<" (not implemented).\n"; }

/// macro to stub a function with return value.
/// Aborts unit tests requiring its definition with a message about the missing linkage
#define STUB_RETVAL(x) { stub_fatal(STUB_API " required"); return x; }

/// macro to stub a void function without a fatal message and with a return value
/// Intended for registration pattern APIs where the function result does not matter to the test
#define STUB_RETVAL_NOP(x) { std::cerr<<"SKIP: "<<STUB_API<<" "<<__func__<<" (not implemented).\n"; return x; }

/** macro to stub a function which returns a reference to dynamic
 *  Aborts unit tests requiring its definition with a message about the missing linkage
 *  \param x underlying or "referred to" type
 */
#define STUB_RETREF(x) { stub_fatal(STUB_API " required"); return *(x *)nullptr; }

/** Same as STUB_RETREF(). TODO: Remove */
#define STUB_RETSTATREF(x) STUB_RETREF(x)

#endif /* SQUID_SRC_TESTS_STUB_H */
Commit	Line	Data
	1	/*
	2	* Copyright (C) 1996-2025 The Squid Software Foundation and contributors
	3	*
	4	* Squid software is distributed under GPLv2+ license and includes
	5	* contributions from numerous individuals and organizations.
	6	* Please see the COPYING and CONTRIBUTORS files for details.
	7	*/
	8
	9	#ifndef SQUID_SRC_TESTS_STUB_H
	10	#define SQUID_SRC_TESTS_STUB_H
	11
	12	/** \group STUB
	13	*
	14	* A set of useful macros to create stub_* files.
	15	*
	16	* Intended for use building unit tests, if a stubbed function is called
	17	* by any code it is linked to it will abort with a message indicating
	18	* which API file is missing from the linked dependencies.
	19	*
	20	* Usage:
	21	* at the top of your intended stub file define STUB_API to be the
	22	* name of the .cc file or library you are providing a stub of
	23	* then include this STUB.h header.
	24	*
	25	* #define STUB_API "foo/libexample.la"
	26	* #include "tests/STUB.h"
	27	*/
	28	#include <iostream>
	29
	30	// Internal Special: the STUB framework requires this function
	31	#define stub_fatal(m) { std::cerr<<"FATAL: "<<(m)<<" for use of "<<__func__<<"\n"; exit(EXIT_FAILURE); }
	32
	33	/// macro to stub a void function.
	34	#define STUB { stub_fatal(STUB_API " required"); }
	35
	36	/// macro to stub a void function without a fatal message
	37	/// Intended for registration pattern APIs where the function result does not matter to the test
	38	#define STUB_NOP { std::cerr<<"SKIP: "<<STUB_API<<" "<<__func__<<" (not implemented).\n"; }
	39
	40	/// macro to stub a function with return value.
	41	/// Aborts unit tests requiring its definition with a message about the missing linkage
	42	#define STUB_RETVAL(x) { stub_fatal(STUB_API " required"); return x; }
	43
	44	/// macro to stub a void function without a fatal message and with a return value
	45	/// Intended for registration pattern APIs where the function result does not matter to the test
	46	#define STUB_RETVAL_NOP(x) { std::cerr<<"SKIP: "<<STUB_API<<" "<<__func__<<" (not implemented).\n"; return x; }
	47
	48	/** macro to stub a function which returns a reference to dynamic
	49	* Aborts unit tests requiring its definition with a message about the missing linkage
	50	* \param x underlying or "referred to" type
	51	*/
	52	#define STUB_RETREF(x) { stub_fatal(STUB_API " required"); return (x )nullptr; }
	53
	54	/** Same as STUB_RETREF(). TODO: Remove */
	55	#define STUB_RETSTATREF(x) STUB_RETREF(x)
	56
	57	#endif /* SQUID_SRC_TESTS_STUB_H */
	58