Source/cmCTest.h

   1 /* Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
   2    file Copyright.txt or https://cmake.org/licensing for details.  */
   3 #pragma once
   4
   5 #include "cmConfigure.h" // IWYU pragma: keep
   6
   7 #include <chrono>
   8 #include <ctime>
   9 #include <map>
  10 #include <memory>
  11 #include <sstream>
  12 #include <string>
  13 #include <vector>
  14
  15 #include <cm/string_view>
  16
  17 #include "cmDuration.h"
  18 #include "cmProcessOutput.h"
  19
  20 class cmCTestBuildHandler;
  21 class cmCTestBuildAndTestHandler;
  22 class cmCTestCoverageHandler;
  23 class cmCTestScriptHandler;
  24 class cmCTestTestHandler;
  25 class cmCTestUpdateHandler;
  26 class cmCTestConfigureHandler;
  27 class cmCTestMemCheckHandler;
  28 class cmCTestSubmitHandler;
  29 class cmCTestUploadHandler;
  30 class cmCTestStartCommand;
  31 class cmGeneratedFileStream;
  32 class cmMakefile;
  33 class cmXMLWriter;
  34
  35 /** \class cmCTest
  36  * \brief Represents a ctest invocation.
  37  *
  38  * This class represents a ctest invocation. It is the top level class when
  39  * running ctest.
  40  *
  41  */
  42 class cmCTest
  43 {
  44 public:
  45   using Encoding = cmProcessOutput::Encoding;
  46   /** Enumerate parts of the testing and submission process.  */
  47   enum Part
  48   {
  49     PartStart,
  50     PartUpdate,
  51     PartConfigure,
  52     PartBuild,
  53     PartTest,
  54     PartCoverage,
  55     PartMemCheck,
  56     PartSubmit,
  57     PartNotes,
  58     PartExtraFiles,
  59     PartUpload,
  60     PartDone,
  61     PartCount // Update names in constructor when adding a part
  62   };
  63
  64   /** Get a testing part id from its string name.  Returns PartCount
  65       if the string does not name a valid part.  */
  66   Part GetPartFromName(const std::string& name);
  67
  68   /** Process Command line arguments */
  69   int Run(std::vector<std::string>&, std::string* output = nullptr);
  70
  71   /**
  72    * Initialize and finalize testing
  73    */
  74   bool InitializeFromCommand(cmCTestStartCommand* command);
  75   void Finalize();
  76
  77   /**
  78    * Process the dashboard client steps.
  79    *
  80    * Steps are enabled using SetTest()
  81    *
  82    * The execution of the steps (or #Part) should look like this:
  83    *
  84    * /code
  85    * ctest foo;
  86    * foo.Initialize();
  87    * // Set some things on foo
  88    * foo.ProcessSteps();
  89    * foo.Finalize();
  90    * /endcode
  91    *
  92    * \sa Initialize(), Finalize(), Part, PartInfo, SetTest()
  93    */
  94   int ProcessSteps();
  95
  96   /**
  97    * A utility function that returns the nightly time
  98    */
  99   struct tm* GetNightlyTime(std::string const& str, bool tomorrowtag);
 100
 101   /**
 102    * Is the tomorrow tag set?
 103    */
 104   bool GetTomorrowTag() const;
 105
 106   /**
 107    * Try to run tests of the project
 108    */
 109   int TestDirectory(bool memcheck);
 110
 111   /** what is the configuration type, e.g. Debug, Release etc. */
 112   std::string const& GetConfigType();
 113   cmDuration GetTimeOut() const;
 114   void SetTimeOut(cmDuration t);
 115
 116   cmDuration GetGlobalTimeout() const;
 117
 118   /** how many test to run at the same time */
 119   int GetParallelLevel() const;
 120   void SetParallelLevel(int);
 121
 122   unsigned long GetTestLoad() const;
 123   void SetTestLoad(unsigned long);
 124
 125   /**
 126    * Check if CTest file exists
 127    */
 128   bool CTestFileExists(const std::string& filename);
 129   bool AddIfExists(Part part, const std::string& file);
 130
 131   /**
 132    * Set the cmake test
 133    */
 134   bool SetTest(const std::string&, bool report = true);
 135
 136   /**
 137    * Set the cmake test mode (experimental, nightly, continuous).
 138    */
 139   void SetTestModel(int mode);
 140   int GetTestModel() const;
 141
 142   std::string GetTestModelString();
 143   static int GetTestModelFromString(const std::string& str);
 144   static std::string CleanString(const std::string& str,
 145                                  std::string::size_type spos = 0);
 146   std::string GetCTestConfiguration(const std::string& name);
 147   void SetCTestConfiguration(const char* name, const std::string& value,
 148                              bool suppress = false);
 149   void EmptyCTestConfiguration();
 150
 151   std::string GetSubmitURL();
 152
 153   /**
 154    * constructor and destructor
 155    */
 156   cmCTest();
 157   ~cmCTest();
 158
 159   cmCTest(const cmCTest&) = delete;
 160   cmCTest& operator=(const cmCTest&) = delete;
 161
 162   /** Set the notes files to be created. */
 163   void SetNotesFiles(const std::string& notes);
 164
 165   void PopulateCustomVector(cmMakefile* mf, const std::string& definition,
 166                             std::vector<std::string>& vec);
 167   void PopulateCustomInteger(cmMakefile* mf, const std::string& def, int& val);
 168
 169   /** Get the current time as string */
 170   std::string CurrentTime();
 171
 172   /** tar/gzip and then base 64 encode a file */
 173   std::string Base64GzipEncodeFile(std::string const& file);
 174   /** base64 encode a file */
 175   std::string Base64EncodeFile(std::string const& file);
 176
 177   /**
 178    * Return the time remaining that the script is allowed to run in
 179    * seconds if the user has set the variable CTEST_TIME_LIMIT. If that has
 180    * not been set it returns a very large duration.
 181    */
 182   cmDuration GetRemainingTimeAllowed();
 183
 184   static cmDuration MaxDuration();
 185
 186   /**
 187    * Open file in the output directory and set the stream
 188    */
 189   bool OpenOutputFile(const std::string& path, const std::string& name,
 190                       cmGeneratedFileStream& stream, bool compress = false);
 191
 192   /** Should we only show what we would do? */
 193   bool GetShowOnly();
 194
 195   bool GetOutputAsJson();
 196
 197   int GetOutputAsJsonVersion();
 198
 199   bool ShouldUseHTTP10() const;
 200
 201   bool ShouldPrintLabels() const;
 202
 203   bool ShouldCompressTestOutput();
 204   bool CompressString(std::string& str);
 205
 206   bool GetStopOnFailure() const;
 207   void SetStopOnFailure(bool stop);
 208
 209   std::chrono::system_clock::time_point GetStopTime() const;
 210   void SetStopTime(std::string const& time);
 211
 212   /** Used for parallel ctest job scheduling */
 213   std::string GetScheduleType() const;
 214   void SetScheduleType(std::string const& type);
 215
 216   /** The max output width */
 217   int GetMaxTestNameWidth() const;
 218   void SetMaxTestNameWidth(int w);
 219
 220   /**
 221    * Run a single executable command and put the stdout and stderr
 222    * in output.
 223    *
 224    * If verbose is false, no user-viewable output from the program
 225    * being run will be generated.
 226    *
 227    * If timeout is specified, the command will be terminated after
 228    * timeout expires. Timeout is specified in seconds.
 229    *
 230    * Argument retVal should be a pointer to the location where the
 231    * exit code will be stored. If the retVal is not specified and
 232    * the program exits with a code other than 0, then the this
 233    * function will return false.
 234    */
 235   bool RunCommand(std::vector<std::string> const& args, std::string* stdOut,
 236                   std::string* stdErr, int* retVal = nullptr,
 237                   const char* dir = nullptr,
 238                   cmDuration timeout = cmDuration::zero(),
 239                   Encoding encoding = cmProcessOutput::Auto);
 240
 241   /**
 242    * Clean/make safe for xml the given value such that it may be used as
 243    * one of the key fields by CDash when computing the buildid.
 244    */
 245   static std::string SafeBuildIdField(const std::string& value);
 246
 247   /** Start CTest XML output file */
 248   void StartXML(cmXMLWriter& xml, bool append);
 249
 250   /** End CTest XML output file */
 251   void EndXML(cmXMLWriter& xml);
 252
 253   /**
 254    * Run command specialized for make and configure. Returns process status
 255    * and retVal is return value or exception.
 256    */
 257   int RunMakeCommand(const std::string& command, std::string& output,
 258                      int* retVal, const char* dir, cmDuration timeout,
 259                      std::ostream& ofs,
 260                      Encoding encoding = cmProcessOutput::Auto);
 261
 262   /** Return the current tag */
 263   std::string GetCurrentTag();
 264
 265   /** Get the path to the build tree */
 266   std::string GetBinaryDir();
 267
 268   /**
 269    * Get the short path to the file.
 270    *
 271    * This means if the file is in binary or
 272    * source directory, it will become /.../relative/path/to/file
 273    */
 274   std::string GetShortPathToFile(const std::string& fname);
 275
 276   enum
 277   {
 278     UNKNOWN = -1,
 279     EXPERIMENTAL = 0,
 280     NIGHTLY = 1,
 281     CONTINUOUS = 2,
 282   };
 283
 284   /** provide some more detailed info on the return code for ctest */
 285   enum
 286   {
 287     UPDATE_ERRORS = 0x01,
 288     CONFIGURE_ERRORS = 0x02,
 289     BUILD_ERRORS = 0x04,
 290     TEST_ERRORS = 0x08,
 291     MEMORY_ERRORS = 0x10,
 292     COVERAGE_ERRORS = 0x20,
 293     SUBMIT_ERRORS = 0x40
 294   };
 295
 296   /** Are we producing XML */
 297   bool GetProduceXML();
 298   void SetProduceXML(bool v);
 299
 300   /**
 301    * Run command specialized for tests. Returns process status and retVal is
 302    * return value or exception. If environment is non-null, it is used to set
 303    * environment variables prior to running the test. After running the test,
 304    * environment variables are restored to their previous values.
 305    */
 306   int RunTest(std::vector<const char*> args, std::string* output, int* retVal,
 307               std::ostream* logfile, cmDuration testTimeOut,
 308               std::vector<std::string>* environment,
 309               Encoding encoding = cmProcessOutput::Auto);
 310
 311   /**
 312    * Get the handler object
 313    */
 314   cmCTestBuildHandler* GetBuildHandler();
 315   cmCTestBuildAndTestHandler* GetBuildAndTestHandler();
 316   cmCTestCoverageHandler* GetCoverageHandler();
 317   cmCTestScriptHandler* GetScriptHandler();
 318   cmCTestTestHandler* GetTestHandler();
 319   cmCTestUpdateHandler* GetUpdateHandler();
 320   cmCTestConfigureHandler* GetConfigureHandler();
 321   cmCTestMemCheckHandler* GetMemCheckHandler();
 322   cmCTestSubmitHandler* GetSubmitHandler();
 323   cmCTestUploadHandler* GetUploadHandler();
 324
 325   /**
 326    * Set the CTest variable from CMake variable
 327    */
 328   bool SetCTestConfigurationFromCMakeVariable(cmMakefile* mf,
 329                                               const char* dconfig,
 330                                               const std::string& cmake_var,
 331                                               bool suppress = false);
 332
 333   /** Decode a URL to the original string.  */
 334   static std::string DecodeURL(const std::string&);
 335
 336   /**
 337    * Should ctect configuration be updated. When using new style ctest
 338    * script, this should be true.
 339    */
 340   void SetSuppressUpdatingCTestConfiguration(bool val);
 341
 342   /**
 343    * Add overwrite to ctest configuration.
 344    *
 345    * The format is key=value
 346    */
 347   void AddCTestConfigurationOverwrite(const std::string& encstr);
 348
 349   /** Create XML file that contains all the notes specified */
 350   int GenerateNotesFile(std::vector<std::string> const& files);
 351
 352   /** Create XML file to indicate that build is complete */
 353   int GenerateDoneFile();
 354
 355   /** Submit extra files to the server */
 356   bool SubmitExtraFiles(const std::string& files);
 357   bool SubmitExtraFiles(std::vector<std::string> const& files);
 358
 359   /** Set the output log file name */
 360   void SetOutputLogFileName(const std::string& name);
 361
 362   /** Set the output JUnit file name */
 363   void SetOutputJUnitFileName(const std::string& name);
 364
 365   /** Set the visual studio or Xcode config type */
 366   void SetConfigType(const std::string& ct);
 367
 368   /** Various log types */
 369   enum
 370   {
 371     DEBUG = 0,
 372     OUTPUT,
 373     HANDLER_OUTPUT,
 374     HANDLER_PROGRESS_OUTPUT,
 375     HANDLER_TEST_PROGRESS_OUTPUT,
 376     HANDLER_VERBOSE_OUTPUT,
 377     WARNING,
 378     ERROR_MESSAGE,
 379     OTHER
 380   };
 381
 382   /** Add log to the output */
 383   void Log(int logType, const char* file, int line, const char* msg,
 384            bool suppress = false);
 385
 386   /** Color values */
 387   enum class Color
 388   {
 389     CLEAR_COLOR = 0,
 390     RED = 31,
 391     GREEN = 32,
 392     YELLOW = 33,
 393     BLUE = 34
 394   };
 395
 396   /** Get color code characters for a specific color */
 397   std::string GetColorCode(Color color) const;
 398
 399   /** The Build ID is assigned by CDash */
 400   void SetBuildID(const std::string& id);
 401   std::string GetBuildID() const;
 402
 403   /** Add file to be submitted */
 404   void AddSubmitFile(Part part, const std::string& name);
 405   std::vector<std::string> const& GetSubmitFiles(Part part) const;
 406   void ClearSubmitFiles(Part part);
 407
 408   /**
 409    * Read the custom configuration files and apply them to the current ctest
 410    */
 411   int ReadCustomConfigurationFileTree(const std::string& dir, cmMakefile* mf);
 412
 413   std::vector<std::string>& GetInitialCommandLineArguments();
 414
 415   /** Set the group to submit to */
 416   void SetSpecificGroup(const char* group);
 417   const char* GetSpecificGroup();
 418
 419   void SetFailover(bool failover);
 420   bool GetFailover() const;
 421
 422   bool GetTestProgressOutput() const;
 423
 424   bool GetVerbose() const;
 425   bool GetExtraVerbose() const;
 426
 427   /** Direct process output to given streams.  */
 428   void SetStreams(std::ostream* out, std::ostream* err);
 429
 430   void AddSiteProperties(cmXMLWriter& xml);
 431
 432   bool GetLabelSummary() const;
 433   bool GetSubprojectSummary() const;
 434
 435   std::string GetCostDataFile();
 436
 437   bool GetOutputTestOutputOnTestFailure() const;
 438
 439   const std::map<std::string, std::string>& GetDefinitions() const;
 440
 441   /** Return the number of times a test should be run */
 442   int GetRepeatCount() const;
 443
 444   enum class Repeat
 445   {
 446     Never,
 447     UntilFail,
 448     UntilPass,
 449     AfterTimeout,
 450   };
 451   Repeat GetRepeatMode() const;
 452
 453   enum class NoTests
 454   {
 455     Legacy,
 456     Error,
 457     Ignore
 458   };
 459   NoTests GetNoTestsMode() const;
 460
 461   void GenerateSubprojectsOutput(cmXMLWriter& xml);
 462   std::vector<std::string> GetLabelsForSubprojects();
 463
 464   void SetRunCurrentScript(bool value);
 465
 466 private:
 467   void SetPersistentOptionIfNotEmpty(const std::string& value,
 468                                      const std::string& optionName);
 469   void AddPersistentMultiOptionIfNotEmpty(const std::string& value,
 470                                           const std::string& optionName);
 471
 472   int GenerateNotesFile(const std::string& files);
 473
 474   void BlockTestErrorDiagnostics();
 475
 476   /**
 477    * Initialize a dashboard run in the given build tree.  The "command"
 478    * argument is non-NULL when running from a command-driven (ctest_start)
 479    * dashboard script, and NULL when running from the CTest command
 480    * line.  Note that a declarative dashboard script does not actually
 481    * call this method because it sets CTEST_COMMAND to drive a build
 482    * through the ctest command line.
 483    */
 484   int Initialize(const char* binary_dir, cmCTestStartCommand* command);
 485
 486   /** parse the option after -D and convert it into the appropriate steps */
 487   bool AddTestsForDashboardType(std::string& targ);
 488
 489   /** read as "emit an error message for an unknown -D value" */
 490   void ErrorMessageUnknownDashDValue(std::string& val);
 491
 492   /** add a variable definition from a command line -D value */
 493   bool AddVariableDefinition(const std::string& arg);
 494
 495   /** set command line arguments read from a test preset */
 496   bool SetArgsFromPreset(const std::string& presetName, bool listPresets);
 497
 498   /** parse and process most common command line arguments */
 499   bool HandleCommandLineArguments(size_t& i, std::vector<std::string>& args,
 500                                   std::string& errormsg);
 501
 502 #if !defined(_WIN32)
 503   /** returns true iff the console supports progress output */
 504   static bool ConsoleIsNotDumb();
 505 #endif
 506
 507   /** returns true iff the console supports progress output */
 508   static bool ProgressOutputSupportedByConsole();
 509
 510   /** returns true iff the console supports colored output */
 511   static bool ColoredOutputSupportedByConsole();
 512
 513   /** handle the -S -SP and -SR arguments */
 514   void HandleScriptArguments(size_t& i, std::vector<std::string>& args,
 515                              bool& SRArgumentSpecified);
 516
 517   /** Reread the configuration file */
 518   bool UpdateCTestConfiguration();
 519
 520   /** Create note from files. */
 521   int GenerateCTestNotesOutput(cmXMLWriter& xml,
 522                                std::vector<std::string> const& files);
 523
 524   /** Check if the argument is the one specified */
 525   static bool CheckArgument(const std::string& arg, cm::string_view varg1,
 526                             const char* varg2 = nullptr);
 527
 528   /** Output errors from a test */
 529   void OutputTestErrors(std::vector<char> const& process_output);
 530
 531   /** Handle the --test-action command line argument */
 532   bool HandleTestActionArgument(const char* ctestExec, size_t& i,
 533                                 const std::vector<std::string>& args);
 534
 535   /** Handle the --test-model command line argument */
 536   bool HandleTestModelArgument(const char* ctestExec, size_t& i,
 537                                const std::vector<std::string>& args);
 538
 539   int RunCMakeAndTest(std::string* output);
 540   int ExecuteTests();
 541
 542   /** return true iff change directory was successful */
 543   bool TryToChangeDirectory(std::string const& dir);
 544
 545   struct Private;
 546   std::unique_ptr<Private> Impl;
 547 };
 548
 549 class cmCTestLogWrite
 550 {
 551 public:
 552   cmCTestLogWrite(const char* data, size_t length)
 553     : Data(data)
 554     , Length(length)
 555   {
 556   }
 557
 558   const char* Data;
 559   size_t Length;
 560 };
 561
 562 inline std::ostream& operator<<(std::ostream& os, const cmCTestLogWrite& c)
 563 {
 564   if (!c.Length) {
 565     return os;
 566   }
 567   os.write(c.Data, c.Length);
 568   os.flush();
 569   return os;
 570 }
 571
 572 #define cmCTestLog(ctSelf, logType, msg)                                      \
 573   do {                                                                        \
 574     std::ostringstream cmCTestLog_msg;                                        \
 575     cmCTestLog_msg << msg;                                                    \
 576     (ctSelf)->Log(cmCTest::logType, __FILE__, __LINE__,                       \
 577                   cmCTestLog_msg.str().c_str());                              \
 578   } while (false)
 579
 580 #define cmCTestOptionalLog(ctSelf, logType, msg, suppress)                    \
 581   do {                                                                        \
 582     std::ostringstream cmCTestLog_msg;                                        \
 583     cmCTestLog_msg << msg;                                                    \
 584     (ctSelf)->Log(cmCTest::logType, __FILE__, __LINE__,                       \
 585                   cmCTestLog_msg.str().c_str(), suppress);                    \
 586   } while (false)