src/tests/STUB.h

   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