unit_test_base.h

Go to the documentation of this file.

#ifndef TEST_UNIT_TEST_BASE_H
#define TEST_UNIT_TEST_BASE_H

// LArSoft libraries
#include "larcorealg/CoreUtils/ProviderPack.h"
#include "larcorealg/TestUtils/ProviderList.h"
#include "larcorealg/TestUtils/ProviderTestHelpers.h"

// utility libraries
#include "fhiclcpp/ParameterSet.h"
#include "fhiclcpp/intermediate_table.h"
#include "fhiclcpp/parse.h"
#include "fhiclcpp/types/Atom.h"
#include "fhiclcpp/types/Comment.h"
#include "fhiclcpp/types/Name.h"
#include "fhiclcpp/types/Table.h"
#include "messagefacility/MessageLogger/MessageLogger.h"

// CET libraries
#include "cetlib/filepath_maker.h"
#include "cetlib/search_path.h"

// C/C++ standard libraries
#include <iostream> // for output before message facility is set up
#include <map>
#include <memory>    // std::unique_ptr<>
#include <stdexcept> // std::logic_error
#include <string>
#include <type_traits> // std::add_rvalue_reference()
#include <utility>     // std::move(), std::forward()

namespace testing {

  namespace details {

    class CommandLineArguments {
    public:
      CommandLineArguments() { Clear(); }

      CommandLineArguments(int argc, char** argv) { ParseArguments(argc, argv); }

      void ParseArguments(int argc, char** argv);

      std::string Executable() const { return exec_name; }

      std::vector<std::string> const& Arguments() const { return args; }

      bool hasArgument(size_t iArg) const { return iArg < args.size(); }

      std::string const& Argument(size_t iArg) const { return args[iArg]; }

    private:
      std::string exec_name;         
      std::vector<std::string> args; 

      void Clear()
      {
        exec_name.clear();
        args.clear();
      }

    }; // class CommandLineArguments

    inline void CommandLineArguments::ParseArguments(int argc, char** argv)
    {
      Clear();
      if (argc == 0) return;

      exec_name = argv[0];

      args.resize(argc - 1);
      std::copy(argv + 1, argv + argc, args.begin());

    } // CommandLineArguments:ParseArguments()

    // forward declaration
    template <typename TestEnv, typename Pack, typename... Provs>
    struct ProviderPackFiller;

  } // namespace details

  struct BasicEnvironmentConfiguration {

    BasicEnvironmentConfiguration() { DefaultInit(); }

    BasicEnvironmentConfiguration(int argc, char** argv) : BasicEnvironmentConfiguration()
    {
      ParseCommandLine(argc, argv);
    }

    BasicEnvironmentConfiguration(std::string name) : BasicEnvironmentConfiguration()
    {
      SetApplicationName(name);
    }

    BasicEnvironmentConfiguration(int argc, char** argv, std::string name)
      : BasicEnvironmentConfiguration(argc, argv)
    {
      SetApplicationName(name);
    }

    std::string ApplicationName() const { return appl_name; }

    std::string ConfigurationPath() const { return config_path; }

    std::string TesterParameterSetPath(std::string name) const
    {
      auto iPath = test_paths.find(name);
      return (iPath == test_paths.end()) ? ("physics.analyzers." + name) : iPath->second;
    }

    std::string MainTesterParameterSetName() const { return main_test_name; }

    std::string MainTesterParameterSetPath() const
    {
      return MainTesterParameterSetName().empty() ?
               "" :
               TesterParameterSetPath(MainTesterParameterSetName());
    }

    std::string ServiceParameterSetPath(std::string name) const
    {
      auto iPath = service_paths.find(name);
      return (iPath == service_paths.end()) ? ("services." + name) : iPath->second;
    } // ServiceParameterSetPath()

    std::string DefaultTesterConfiguration(std::string tester_name) const
    {
      return analyzers_default_cfg.at(tester_name);
    }

    std::string DefaultServiceConfiguration(std::string service_name) const
    {
      return services_default_cfg.at(service_name);
    }

    std::string DefaultConfiguration() const { return BuildDefaultConfiguration(); }

    std::string ExecutablePath() const { return arguments.Executable(); }

    std::vector<std::string> const& EexcutableArguments() const { return arguments.Arguments(); }



    void SetApplicationName(std::string name) { appl_name = name; }

    void SetConfigurationPath(std::string path) { config_path = path; }

    void SetMainTesterParameterSetName(std::string name) { main_test_name = name; }

    void SetTesterParameterSetPath(std::string test_name, std::string path)
    {
      test_paths[test_name] = path;
    }

    void SetMainTesterParameterSetPath(std::string path)
    {
      if (MainTesterParameterSetName().empty()) {
        throw std::logic_error("Request setting configuration of non-existent main tester");
      }
      SetTesterParameterSetPath(MainTesterParameterSetName(), path);
    }

    void SetServiceParameterSetPath(std::string service_name, std::string path)
    {
      service_paths[service_name] = path;
    }

    void AddDefaultServiceConfiguration(std::string service_name, std::string service_cfg)
    {
      services_default_cfg[service_name] = service_cfg;
    }

    void AddDefaultTesterConfiguration(std::string tester_name, std::string tester_cfg)
    {
      analyzers_default_cfg[tester_name] = tester_cfg;
    }

    void AddDefaultTesterConfiguration(std::string tester_cfg)
    {
      if (MainTesterParameterSetName().empty()) {
        throw std::logic_error("Request adding configuration of non-existent main tester");
      }
      AddDefaultTesterConfiguration(MainTesterParameterSetName(), tester_cfg);
    }


  protected:
    using ConfigurationMap_t = std::map<std::string, std::string>;
    using PathMap_t = std::map<std::string, std::string>;

    std::string appl_name;      
    std::string config_path;    
    std::string main_test_name; 
    std::string main_test_path; 

    static std::string DefaultApplicationName() { return "Test"; }

    ConfigurationMap_t services_default_cfg;
    ConfigurationMap_t analyzers_default_cfg;

    PathMap_t test_paths;
    PathMap_t service_paths;

    void ParseCommandLine(int argc, char** argv)
    {
      arguments.ParseArguments(argc, argv);
      if (arguments.hasArgument(0)) SetConfigurationPath(arguments.Argument(0)); // first argument
    }

    void DefaultInit()
    {
      SetApplicationName(DefaultApplicationName());
      SetMainTesterParameterSetName("");
      // a destination which will react to all messages from DEBUG up:
      AddDefaultServiceConfiguration("message",
                                     R"(
           debugModules: [ '*' ]
           destinations : {
             stdout: {
               type:      cout
               threshold: DEBUG
               categories: {
                 default: {
                   limit: -1
                 }
               } // categories
             } // stdout
             statistics: {type:cout}
           } // destinations
         )");
    } // DefaultInit()

    std::string BuildDefaultServiceConfiguration() const
    {
      return BuildServiceConfiguration(services_default_cfg);
    }

    std::string BuildDefaultTestConfiguration() const
    {
      return BuildTestConfiguration(analyzers_default_cfg);
    }

    std::string BuildDefaultConfiguration() const
    {
      return BuildConfiguration(services_default_cfg, analyzers_default_cfg);
    }

    static std::string BuildServiceConfiguration(ConfigurationMap_t const& services)
    {
      std::string cfg;
      cfg += "\nservices: {";
      for (auto const& service_info : services) {
        cfg += "\n  " + service_info.first + ": {";
        cfg += "\n" + service_info.second;
        cfg += "\n  } # " + service_info.first;
      } // for services
      cfg += "\n} # services"
             "\n";
      return cfg;
    } // BuildServiceConfiguration()

    static std::string BuildTestConfiguration(ConfigurationMap_t const& analyzers)
    {
      std::string cfg;
      cfg += "\nphysics: {"
             "\n  analyzers: {";
      for (auto const& module_info : analyzers) {
        cfg += "\n  " + module_info.first + ": {";
        cfg += "\n" + module_info.second;
        cfg += "\n  } # " + module_info.first;
      } // for analyzers
      cfg += "\n  } # analyzers"
             "\n} # physics";
      return cfg;
    } // BuildServiceConfiguration()

    static std::string BuildConfiguration(ConfigurationMap_t const& services,
                                          ConfigurationMap_t const& modules)
    {
      std::string cfg;
      cfg += BuildServiceConfiguration(services);
      cfg += BuildTestConfiguration(modules);
      return cfg;
    } // BuildConfiguration()

  private:
    details::CommandLineArguments arguments; 

  }; // class BasicEnvironmentConfiguration<>

  template <typename RES>
  class TestSharedGlobalResource {
    using Resource_t = RES;

  public:
    using ResourcePtr_t = std::shared_ptr<Resource_t>;


    static void AddSharedResource(std::string res_name, ResourcePtr_t res_ptr)
    {
      Resources[res_name] = res_ptr;
    }

    static void AddDefaultSharedResource(ResourcePtr_t res_ptr)
    {
      AddSharedResource(std::string(), res_ptr);
    }

    template <typename... Args>
    static ResourcePtr_t ProvideSharedResource(std::string res_name, ResourcePtr_t res_ptr)
    {
      if (hasResource(res_name)) return ResourcePtr_t();
      AddSharedResource(res_name, res_ptr);
      return res_ptr;
    }

    template <typename... Args>
    static ResourcePtr_t ProvideDefaultSharedResource(ResourcePtr_t res_ptr)
    {
      return ProvideSharedResource(std::string(), res_ptr);
    }

    static bool ReplaceSharedResource(std::string res_name,
                                      Resource_t const* old_res_ptr,
                                      ResourcePtr_t res_ptr)
    {
      ResourcePtr_t current_res_ptr = ShareResource();
      if (current_res_ptr.get() != old_res_ptr) return false;
      AddSharedResource(res_name, res_ptr);
      return true;
    }
    static bool ReplaceSharedResource(std::string res_name,
                                      ResourcePtr_t old_res_ptr,
                                      ResourcePtr_t res_ptr)
    {
      return ReplaceSharedResource(res_name, old_res_ptr.get(), res_ptr);
    }

    static bool ReplaceDefaultSharedResource(Resource_t const* old_res_ptr, ResourcePtr_t res_ptr)
    {
      return ReplaceSharedResource(std::string(), old_res_ptr, res_ptr);
    }
    static bool ReplaceDefaultSharedResource(ResourcePtr_t old_res_ptr, ResourcePtr_t res_ptr)
    {
      return ReplaceSharedResource(std::string(), old_res_ptr, res_ptr);
    }

    template <typename... Args>
    static ResourcePtr_t CreateResource(std::string res_name, Args&&... args)
    {
      ResourcePtr_t res_ptr(new Resource_t(std::forward<Args>(args)...));
      AddSharedResource(res_name, res_ptr);
      return res_ptr;
    }

    template <typename... Args>
    static void CreateDefaultResource(Args&&... args)
    {
      CreateResource(std::string(), std::forward<Args>(args)...);
    }

    template <typename... Args>
    static ResourcePtr_t ProposeSharedResource(std::string res_name, Args&&... args)
    {
      return hasResource(res_name) ? ResourcePtr_t() :
                                     CreateResource(res_name, std::forward<Args>(args)...);
    }

    template <typename... Args>
    static ResourcePtr_t ProposeDefaultSharedResource(Args&&... args)
    {
      return ProposeSharedResource(std::string(), std::forward<Args>(args)...);
    }



    static bool hasResource(std::string name = "")
    {
      auto iRes = Resources.find(name);
      return (iRes != Resources.end()) && bool(iRes->second);
    }

    static ResourcePtr_t ShareResource(std::string name = "")
    {
      auto iRes = Resources.find(name);
      return (iRes == Resources.end()) ? ResourcePtr_t() : iRes->second;
    }

    static Resource_t& Resource(std::string name = "") { return *(Resources.at(name).get()); }


    static Resource_t& DestroyResource(std::string name = "") { Resources.erase(name); }

  private:
    static std::map<std::string, ResourcePtr_t> Resources;

  }; // class TestSharedGlobalResource<>

  template <typename RES>
  std::map<std::string, typename TestSharedGlobalResource<RES>::ResourcePtr_t>
    TestSharedGlobalResource<RES>::Resources;

  template <typename ConfigurationClass>
  class BasicTesterEnvironment {

  public:
    using Configuration_t = ConfigurationClass;

    BasicTesterEnvironment(bool bSetup = true)
    {
      if (bSetup) Setup();
    }


    BasicTesterEnvironment(Configuration_t const& configurer, bool bSetup = true)
      : config(configurer)
    {
      if (bSetup) Setup();
    }
    BasicTesterEnvironment(Configuration_t&& configurer, bool bSetup = true) : config(configurer)
    {
      if (bSetup) Setup();
    }

    virtual ~BasicTesterEnvironment();


    fhicl::ParameterSet const& Parameters() const { return params; }

    fhicl::ParameterSet ServiceParameters(std::string service_name) const
    {
      return params.get<fhicl::ParameterSet>(config.ServiceParameterSetPath(service_name));
    }

    fhicl::ParameterSet TesterParameters(std::string test_name) const
    {
      return params.get<fhicl::ParameterSet>(config.TesterParameterSetPath(test_name));
    }

    fhicl::ParameterSet TesterParameters() const
    {
      if (config.MainTesterParameterSetName().empty())
        return {};
      else
        return TesterParameters(config.MainTesterParameterSetName());
    }


    static fhicl::ParameterSet CompileParameterSet(std::string cfg);

  protected:
    Configuration_t const& Config() const { return config; }

    virtual void Setup();

    virtual void Configure();

    virtual fhicl::ParameterSet DefaultParameters() const
    {
      return CompileParameterSet(config.DefaultConfiguration());
    }

    virtual void SetupMessageFacility(fhicl::ParameterSet const& pset,
                                      std::string appl_name = "") const;
    virtual void SetupMessageFacility() const
    {
      SetupMessageFacility(Parameters(), config.ApplicationName());
    }

    static fhicl::ParameterSet ParseParameters(std::string config_path);

  private:
    struct Options_t {
      bool MessageLevels = false; 
    };                            // Options_t

    Configuration_t config; 
    Options_t options;      

    void ParseEnvironmentOptions();

    fhicl::ParameterSet params; 

  }; // class BasicTesterEnvironment<>

  //****************************************************************************
  template <typename ConfigurationClass>
  class TesterEnvironment : public BasicTesterEnvironment<ConfigurationClass> {
    using TesterEnvBase_t = BasicTesterEnvironment<ConfigurationClass>;
    using TesterEnv_t = TesterEnvironment<ConfigurationClass>;

  public:
    // inherit constructors
    using TesterEnvBase_t::TesterEnvBase_t;

    template <typename Prov, typename... Args>
    Prov* SetupProvider(Args&&... args)
    {
      if (!providers.setup<Prov>(std::forward<Args>(args)...))
        throw std::runtime_error("Provider already exists!");
      return providers.getPointer<Prov>();
    }

    template <typename Prov, typename... Args>
    Prov* SetupProviderFromService(std::string name, Args&&... args)
    {
      return SetupProvider<Prov>(this->ServiceParameters(name, std::forward<Args>(args)...));
    }

    template <typename Prov>
    Prov* AcquireProvider(std::unique_ptr<Prov>&& prov)
    {
      if (!providers.acquire(std::move(prov))) throw std::runtime_error("Provider already exists!");
      return providers.getPointer<Prov>();
    }

    template <typename Interface, typename Prov, typename... Args>
    Prov* SetupProviderFor(Args&&... args)
    {
      auto prov = SetupProvider<Prov>(std::forward<Args>(args)...);
      providers.set_alias<Prov, Interface>();
      return prov;
    }

    template <typename Interface, typename Prov, typename... Args>
    Prov* SetupProviderFromServiceFor(std::string name, Args&&... args)
    {
      auto* prov = SetupProviderFromService<Prov>(name, std::forward<Args>(args)...);
      providers.set_alias<Prov, Interface>();
      return prov;
    }

    template <typename Interface, typename Prov>
    Prov* AcquireProviderFor(std::unique_ptr<Prov>&& prov)
    {
      auto prov_ptr = prov.get();
      providers.acquire(std::move(prov));
      providers.set_alias<Prov, Interface>();
      return prov_ptr;
    }

    template <typename Prov>
    Prov* SimpleProviderSetup()
    {
      return simpleEnvironmentSetup<Prov>(*this);
    }

    template <typename Prov>
    void DropProvider()
    {
      if (!providers.erase<Prov>()) throw std::runtime_error("Provider not present!");
    }

    template <typename Prov>
    Prov const* Provider() const
    {
      return providers.getPointer<Prov>();
    }

    template <typename... Provs>
    void FillProviderPack(lar::ProviderPack<Provs...>& pack) const
    {
      details::ProviderPackFiller<TesterEnv_t, lar::ProviderPack<Provs...>, Provs...>::fill(*this,
                                                                                            pack);
    } // FillProviderPack()

    template <typename Prov>
    typename Prov::providers_type ProviderPackFor() const
    {
      typename Prov::providers_type pack;
      FillProviderPack(pack);
      return pack;
    } // ProviderPackFor()

  protected:
    ProviderList providers; 
  };                        // class TesterEnvironment<>

  // Note: this function is expected to be used with automatic type detection;
  // the rules on "universal references" dictate that if config is a (l-value)
  // reference, CONFIG itself is a l-value reference. We don't want to create
  // a TesterEnvironment<Config&>, so we explicitly remove the reference from
  // CONFIG (decay does that and aso removes the constantness, that we also
  // don't want to be embedded in CONFIG).
  template <typename CONFIG,
            typename TESTENV = TesterEnvironment<std::decay_t<CONFIG>>,
            typename... ARGS>
  TESTENV CreateTesterEnvironment(CONFIG&& config, ARGS... other_args)
  {
    return TESTENV(std::forward<CONFIG>(config), std::forward<ARGS>(other_args)...);
  }

  //****************************************************************************
  namespace details {
    template <typename TestEnv, typename Pack, typename Prov, typename... Others>
    struct ProviderPackFiller<TestEnv, Pack, Prov, Others...> {
      static void fill(TestEnv const& env, Pack& pack)
      {
        pack.set(env.template Provider<Prov>());
        ProviderPackFiller<TestEnv, Pack, Others...>::fill(env, pack);
      } // fill()

    }; // ProviderPackFiller<TestEnv, Pack, Prov, Others...>

    // end-of-recursion specialisation
    template <typename TestEnv, typename Pack>
    struct ProviderPackFiller<TestEnv, Pack> {
      static void fill(TestEnv const&, Pack&) {}
    }; // ProviderPackFiller<>

  } // namespace details

  //****************************************************************************
  template <typename ConfigurationClass>
  BasicTesterEnvironment<ConfigurationClass>::~BasicTesterEnvironment()
  {
    mf::LogInfo("Test") << config.ApplicationName() << " completed.";
  }

  template <typename ConfigurationClass>
  fhicl::ParameterSet BasicTesterEnvironment<ConfigurationClass>::CompileParameterSet(
    std::string cfg)
  {
    fhicl::ParameterSet global_pset;
    global_pset = fhicl::ParameterSet::make(cfg);
    return global_pset;
  }

  template <typename ConfigurationClass>
  fhicl::ParameterSet BasicTesterEnvironment<ConfigurationClass>::ParseParameters(
    std::string config_path)
  {
    // configuration file lookup policy
    char const* fhicl_env = getenv("FHICL_FILE_PATH");
    std::string search_path = fhicl_env ? std::string(fhicl_env) + ":" : ".:";
    cet::filepath_first_absolute_or_lookup_with_dot policy(search_path);

    // parse a configuration file; obtain intermediate form
    auto table = fhicl::parse_document(config_path, policy);
    return fhicl::ParameterSet::make(table);
  }

  template <typename ConfigurationClass>
  void BasicTesterEnvironment<ConfigurationClass>::Configure()
  {
    std::string config_path = config.ConfigurationPath();
    params = config_path.empty() ? DefaultParameters() : ParseParameters(config_path);
  }

  template <typename ConfigurationClass>
  void BasicTesterEnvironment<ConfigurationClass>::SetupMessageFacility(
    fhicl::ParameterSet const& pset,
    std::string appl_name /* = "" */) const
  {
    fhicl::ParameterSet mf_pset;

    if (!pset.get_if_present(config.ServiceParameterSetPath("message"), mf_pset)) {
      mf_pset = CompileParameterSet(config.DefaultServiceConfiguration("message"));
      std::cout << "Using default message facility configuration:\n"
                << mf_pset.to_indented_string(1) << std::endl;
    } // if no configuration is available

    mf::StartMessageFacility(mf_pset);
    if (!appl_name.empty()) mf::SetApplicationName(appl_name);
    mf::SetContextIteration("Initialization");
    if (options.MessageLevels) {
      std::cout << "Printing message levels in 'MessageFacility' category." << std::endl;

      mf::LogProblem("MessageFacility") << "Error messages are shown.";
      mf::LogPrint("MessageFacility") << "Warning messages are shown.";
      mf::LogVerbatim("MessageFacility") << "Info messages are shown.";
      mf::LogTrace("MessageFacility") << "Debug messages are shown.";
      MF_LOG_TRACE("MessageFacility")
        << "MF_LOG_TRACE/MF_LOG_DEBUG messages are not compiled away.";
    } // if print message levels
    mf::LogInfo("MessageFacility") << "MessageFacility started.";
    mf::SetContextSinglet("main");
  }

  template <typename ConfigurationClass>
  void BasicTesterEnvironment<ConfigurationClass>::Setup()
  {
    Configure();
    ParseEnvironmentOptions();
    SetupMessageFacility();

    // Optionally print the configuration
    {
      mf::LogInfo msg("Configuration");
      msg << "Complete configuration (";
      if (config.ConfigurationPath().empty())
        msg << "default";
      else
        msg << "'" << config.ConfigurationPath() << "'";
      msg << "):\n" << Parameters().to_indented_string(1);
    }
    mf::LogInfo("Test") << config.ApplicationName() << " base setup complete.";
  }

  template <typename ConfigurationClass>
  void BasicTesterEnvironment<ConfigurationClass>::ParseEnvironmentOptions()
  {

    struct OptionsFromConfig_t {
      fhicl::Atom<bool> messageLevels{
        fhicl::Name("messageLevels"),
        fhicl::Comment("prints a message per level (to verify the visible ones"),
        false // default: no
      };
      fhicl::Atom<bool> printOptions{
        fhicl::Name("printOptions"),
        fhicl::Comment("prints a the list of options (this is one of them!)"),
        false // default: no
      };
    }; // OptionsFromConfig_t

    struct ValidationHelper {
      static void printDummy(std::ostream& out)
      {
        fhicl::Table<OptionsFromConfig_t>(fhicl::Name("test"),
                                          fhicl::Comment("Test environment options"))
          .print_allowed_configuration(out);
      } // printDummy()

      static fhicl::Table<OptionsFromConfig_t> validate(fhicl::ParameterSet const& pset)
      {
        try {
          return fhicl::Table<OptionsFromConfig_t>(pset, {});
        }
        catch (...) {
          std::cerr << "Error parsing environment test options! Valid options:" << std::endl;
          ValidationHelper::printDummy(std::cerr);
          throw;
        }
      } // validate()
    };

    fhicl::ParameterSet pset = params.get<fhicl::ParameterSet>("test", {});

    // automatically performs validation
    fhicl::Table<OptionsFromConfig_t> configTable(ValidationHelper::validate(pset));

    if (configTable().printOptions()) {
      std::cout << "The following options can be passed to the test environment"
                << " by putting them in the \"test: {}\" table of the configuration file:"
                << std::endl;
      ValidationHelper::printDummy(std::cout);
    }

    options.MessageLevels = configTable().messageLevels();
  } // BasicTesterEnvironment<>::ParseEnvironmentOptions()

} // namespace testing

#endif // TEST_UNIT_TEST_BASE_H