1 /*
2 * Copyright (c) 2017-2020 Arm Limited.
3 *
4 * SPDX-License-Identifier: MIT
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining a copy
7 * of this software and associated documentation files (the "Software"), to
8 * deal in the Software without restriction, including without limitation the
9 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10 * sell copies of the Software, and to permit persons to whom the Software is
11 * furnished to do so, subject to the following conditions:
12 *
13 * The above copyright notice and this permission notice shall be included in all
14 * copies or substantial portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22 * SOFTWARE.
23 */
24 #ifndef ARM_COMPUTE_TEST_FRAMEWORK
25 #define ARM_COMPUTE_TEST_FRAMEWORK
26
27 #include "DatasetModes.h"
28 #include "Exceptions.h"
29 #include "Profiler.h"
30 #include "TestCase.h"
31 #include "TestCaseFactory.h"
32 #include "TestResult.h"
33 #include "Utils.h"
34 #include "instruments/Instruments.h"
35 #include "printers/Printer.h"
36
37 #include <algorithm>
38 #include <chrono>
39 #include <map>
40 #include <memory>
41 #include <numeric>
42 #include <ostream>
43 #include <set>
44 #include <sstream>
45 #include <string>
46 #include <vector>
47
48 namespace arm_compute
49 {
50 namespace test
51 {
52 namespace framework
53 {
54 class TestFilter;
55
56 /** Framework configuration structure */
57 struct FrameworkConfig
58 {
59 std::vector<framework::InstrumentsDescription> instruments{}; /**< Instrument types that will be used for benchmarking. */
60 std::string name_filter{}; /**< Regular expression to filter tests by name. Only matching tests will be executed. */
61 std::string id_filter{}; /**< String to match selected test ids. Only matching tests will be executed. */
62 DatasetMode mode{ DatasetMode::ALL }; /**< Dataset mode. */
63 int num_iterations{ 1 }; /**< Number of iterations per test. */
64 float cooldown_sec{ -1.f }; /**< Delay between tests in seconds. */
65 LogLevel log_level{ LogLevel::NONE }; /**< Verbosity of the output. */
66 };
67
68 /** Information about a test case.
69 *
70 * A test can be identified either via its id or via its name. Additionally
71 * each test is tagged with the data set mode in which it will be used and
72 * its status.
73 *
74 * @note The mapping between test id and test name is not guaranteed to be
75 * stable. It is subject to change as new test are added.
76 */
77 struct TestInfo
78 {
79 int id; /**< Test ID */
80 std::string name; /**< Test name */
81 DatasetMode mode; /**< Test data set mode */
82 TestCaseFactory::Status status; /**< Test status */
83 };
84
85 inline bool operator<(const TestInfo &lhs, const TestInfo &rhs)
86 {
87 return lhs.id < rhs.id;
88 }
89
90 /** Main framework class.
91 *
92 * Keeps track of the global state, owns all test cases and collects results.
93 */
94 class Framework final
95 {
96 public:
97 /** Access to the singleton.
98 *
99 * @return Unique instance of the framework class.
100 */
101 static Framework &get();
102
103 /** Supported instrument types for benchmarking.
104 *
105 * @return Set of all available instrument types.
106 */
107 std::set<InstrumentsDescription> available_instruments() const;
108
109 /** Init the framework.
110 *
111 * @see TestFilter::TestFilter for the format of the string to filter ids.
112 *
113 * @param[in] config Framework configuration meta-data.
114 */
115 void init(const FrameworkConfig &config);
116
117 /** Add a new test suite.
118 *
119 * @warning Cannot be used at execution time. It can only be used for
120 * registering test cases.
121 *
122 * @param[in] name Name of the added test suite.
123 *
124 * @return Name of the current test suite.
125 */
126 void push_suite(std::string name);
127
128 /** Remove innermost test suite.
129 *
130 * @warning Cannot be used at execution time. It can only be used for
131 * registering test cases.
132 */
133 void pop_suite();
134
135 /** Add a test case to the framework.
136 *
137 * @param[in] test_name Name of the new test case.
138 * @param[in] mode Mode in which to include the test.
139 * @param[in] status Status of the test case.
140 */
141 template <typename T>
142 void add_test_case(std::string test_name, DatasetMode mode, TestCaseFactory::Status status);
143
144 /** Add a data test case to the framework.
145 *
146 * @param[in] test_name Name of the new test case.
147 * @param[in] mode Mode in which to include the test.
148 * @param[in] status Status of the test case.
149 * @param[in] description Description of @p data.
150 * @param[in] data Data that will be used as input to the test.
151 */
152 template <typename T, typename D>
153 void add_data_test_case(std::string test_name, DatasetMode mode, TestCaseFactory::Status status, std::string description, D &&data);
154
155 /** Add info string for the next expectation/assertion.
156 *
157 * @param[in] info Info string.
158 */
159 void add_test_info(std::string info);
160
161 /** Clear the collected test info. */
162 void clear_test_info();
163
164 /** Check if any info has been registered.
165 *
166 * @return True if there is test info.
167 */
168 bool has_test_info() const;
169
170 /** Print test info.
171 *
172 * @param[out] os Output stream.
173 */
174 void print_test_info(std::ostream &os) const;
175
176 /** Tell the framework that execution of a test starts.
177 *
178 * @param[in] info Test info.
179 */
180 void log_test_start(const TestInfo &info);
181
182 /** Tell the framework that a test case is skipped.
183 *
184 * @param[in] info Test info.
185 */
186 void log_test_skipped(const TestInfo &info);
187
188 /** Tell the framework that a test case finished.
189 *
190 * @param[in] info Test info.
191 */
192 void log_test_end(const TestInfo &info);
193
194 /** Tell the framework that the currently running test case failed a non-fatal expectation.
195 *
196 * @param[in] error Description of the error.
197 */
198 void log_failed_expectation(const TestError &error);
199
200 /** Print the debug information that has already been logged
201 *
202 * @param[in] info Description of the log info.
203 */
204 void log_info(const std::string &info);
205
206 /** Number of iterations per test case.
207 *
208 * @return Number of iterations per test case.
209 */
210 int num_iterations() const;
211
212 /** Set number of iterations per test case.
213 *
214 * @param[in] num_iterations Number of iterations per test case.
215 */
216 void set_num_iterations(int num_iterations);
217
218 /** Should errors be caught or thrown by the framework.
219 *
220 * @return True if errors are thrown.
221 */
222 bool throw_errors() const;
223
224 /** Set whether errors are caught or thrown by the framework.
225 *
226 * @param[in] throw_errors True if errors should be thrown.
227 */
228 void set_throw_errors(bool throw_errors);
229
230 /** Indicates if test execution is stopped after the first failed test.
231 *
232 * @return True if the execution is going to be aborted after the first failed test.
233 */
234 bool stop_on_error() const;
235
236 /** Set whether to abort execution after the first failed test.
237 *
238 * @param[in] stop_on_error True if execution is going to be aborted after first failed test.
239 */
240 void set_stop_on_error(bool stop_on_error);
241
242 /** Indicates if a test should be marked as failed when its assets are missing.
243 *
244 * @return True if a test should be marked as failed when its assets are missing.
245 */
246 bool error_on_missing_assets() const;
247
248 /** Set whether a test should be considered as failed if its assets cannot be found.
249 *
250 * @param[in] error_on_missing_assets True if a test should be marked as failed when its assets are missing.
251 */
252 void set_error_on_missing_assets(bool error_on_missing_assets);
253
254 /** Run all enabled test cases.
255 *
256 * @return True if all test cases executed successful.
257 */
258 bool run();
259
260 /** Set the result for an executed test case.
261 *
262 * @param[in] info Test info.
263 * @param[in] result Execution result.
264 */
265 void set_test_result(TestInfo info, TestResult result);
266
267 /** Use the specified printer to output test results from the last run.
268 *
269 * This method can be used if the test results need to be obtained using a
270 * different printer than the one managed by the framework.
271 *
272 * @param[in] printer Printer used to output results.
273 */
274 void print_test_results(Printer &printer) const;
275
276 /** Factory method to obtain a configured profiler.
277 *
278 * The profiler enables all instruments that have been passed to the @ref
279 * init method.
280 *
281 * @return Configured profiler to collect benchmark results.
282 */
283 Profiler get_profiler() const;
284
285 /** Set the printer used for the output of test results.
286 *
287 * @param[in] printer Pointer to a printer.
288 */
289 void add_printer(Printer *printer);
290
291 /** List of @ref TestInfo's.
292 *
293 * @return Vector with all test ids.
294 */
295 std::vector<TestInfo> test_infos() const;
296
297 /** Get the current logging level
298 *
299 * @return The current logging level.
300 */
301 LogLevel log_level() const;
302 /** Sets instruments info
303 *
304 * @note TODO(COMPMID-2638) : Remove once instruments are transferred outside the framework.
305 *
306 * @param[in] instr_info Instruments info to set
307 */
308 void set_instruments_info(InstrumentsInfo instr_info);
309
310 private:
311 Framework();
312 ~Framework() = default;
313
314 Framework(const Framework &) = delete;
315 Framework &operator=(const Framework &) = delete;
316
317 void run_test(const TestInfo &info, TestCaseFactory &test_factory);
318 std::map<TestResult::Status, int> count_test_results() const;
319
320 /** Returns the current test suite name.
321 *
322 * @warning Cannot be used at execution time to get the test suite of the
323 * currently executed test case. It can only be used for registering test
324 * cases.
325 *
326 * @return Name of the current test suite.
327 */
328 std::string current_suite_name() const;
329
330 /* Perform func on all printers */
331 template <typename F>
332 void func_on_all_printers(F &&func);
333
334 std::vector<std::string> _test_suite_name{};
335 std::vector<std::unique_ptr<TestCaseFactory>> _test_factories{};
336 std::map<TestInfo, TestResult> _test_results{};
337 int _num_iterations{ 1 };
338 float _cooldown_sec{ -1.f };
339 bool _throw_errors{ false };
340 bool _stop_on_error{ false };
341 bool _error_on_missing_assets{ false };
342 std::vector<Printer *> _printers{};
343
344 using create_function = std::unique_ptr<Instrument>();
345 std::map<InstrumentsDescription, create_function *> _available_instruments{};
346
347 std::set<framework::InstrumentsDescription> _instruments{ std::pair<InstrumentType, ScaleFactor>(InstrumentType::NONE, ScaleFactor::NONE) };
348 std::unique_ptr<TestFilter> _test_filter;
349 LogLevel _log_level{ LogLevel::ALL };
350 const TestInfo *_current_test_info{ nullptr };
351 TestResult *_current_test_result{ nullptr };
352 std::vector<std::string> _test_info{};
353 };
354
355 template <typename T>
add_test_case(std::string test_name,DatasetMode mode,TestCaseFactory::Status status)356 inline void Framework::add_test_case(std::string test_name, DatasetMode mode, TestCaseFactory::Status status)
357 {
358 _test_factories.emplace_back(support::cpp14::make_unique<SimpleTestCaseFactory<T>>(current_suite_name(), std::move(test_name), mode, status));
359 }
360
361 template <typename T, typename D>
add_data_test_case(std::string test_name,DatasetMode mode,TestCaseFactory::Status status,std::string description,D && data)362 inline void Framework::add_data_test_case(std::string test_name, DatasetMode mode, TestCaseFactory::Status status, std::string description, D &&data)
363 {
364 // WORKAROUND for GCC 4.9
365 // The function should get *it which is tuple but that seems to trigger a
366 // bug in the compiler.
367 auto tmp = std::unique_ptr<DataTestCaseFactory<T, decltype(*std::declval<D>())>>(new DataTestCaseFactory<T, decltype(*std::declval<D>())>(current_suite_name(), std::move(test_name), mode, status,
368 std::move(description), *data));
369 _test_factories.emplace_back(std::move(tmp));
370 }
371 } // namespace framework
372 } // namespace test
373 } // namespace arm_compute
374 #endif /* ARM_COMPUTE_TEST_FRAMEWORK */
375