From e94114cc6d1ef062c7739351c758c91cf61cd8c5 Mon Sep 17 00:00:00 2001 From: Thomas Thomassen Date: Tue, 27 Feb 2024 10:37:46 +0100 Subject: [PATCH 1/3] Add Yard configuration and correct Yard syntax. --- .gitignore | 7 +++++++ .yardopts | 7 +++++++ src/testup/api.rb | 2 +- src/testup/command.rb | 2 +- src/testup/core.rb | 2 +- src/testup/coverage.rb | 2 +- src/testup/coverage_discoverer.rb | 2 +- src/testup/log.rb | 2 +- src/testup/manifest.rb | 2 +- src/testup/report/collection.rb | 2 +- src/testup/report/test.rb | 2 +- src/testup/report/test_coverage.rb | 2 +- src/testup/report/test_suite.rb | 4 ++-- src/testup/sketchup_test_utilities.rb | 2 +- src/testup/test_discoverer.rb | 2 +- src/testup/ui/runner.rb | 2 +- 16 files changed, 29 insertions(+), 15 deletions(-) create mode 100644 .yardopts diff --git a/.gitignore b/.gitignore index 0105887..fccf9ce 100644 --- a/.gitignore +++ b/.gitignore @@ -75,3 +75,10 @@ Gemfile.lock src/testup/ui/js/*.* src/testup/ui/images/* + +############ +## Yard +############ + +.yardoc/ +doc/ diff --git a/.yardopts b/.yardopts new file mode 100644 index 0000000..a1fd510 --- /dev/null +++ b/.yardopts @@ -0,0 +1,7 @@ +--title "TestUp 2 for SketchUp - A GUI wrapper for running Minitest in SketchUp" +--no-private +--markup markdown +src/**/*.rb +- +README.md +LICENSE diff --git a/src/testup/api.rb b/src/testup/api.rb index 6e016af..59943d5 100644 --- a/src/testup/api.rb +++ b/src/testup/api.rb @@ -129,7 +129,7 @@ def self.run_test_suite(test_suite, options: {}) # @param [String] title # @param [String] path # @param [Array] results - # @result [Report::TestSuite] + # @return [Report::TestSuite] def self.test_suite_from_results(title, path, results) tests = {} results.each { |result| diff --git a/src/testup/command.rb b/src/testup/command.rb index d70b745..18431fa 100644 --- a/src/testup/command.rb +++ b/src/testup/command.rb @@ -3,7 +3,7 @@ module TestUp # return a UI::Command object. So instead this module is used that will extend # the instance created with it's #create method. # -# @example +# @example Creating a Command object: # cmd = Command.create('Hello World') { # Extension.hello_world # } diff --git a/src/testup/core.rb b/src/testup/core.rb index 7007cc5..eed9162 100644 --- a/src/testup/core.rb +++ b/src/testup/core.rb @@ -83,7 +83,7 @@ def self.toggle_verbose_console_tests end # TODO(thomthom): Move this method. Maybe to the Reporter class if the - # @num_tests_being_run instance variable also can be moved there. + # `@num_tests_being_run`` instance variable also can be moved there. def self.update_testing_progress(num_tests_run) progress = TaskbarProgress.new progress.set_value(num_tests_run, @num_tests_being_run) diff --git a/src/testup/coverage.rb b/src/testup/coverage.rb index d00d912..3b7a393 100644 --- a/src/testup/coverage.rb +++ b/src/testup/coverage.rb @@ -11,7 +11,7 @@ module TestUp # TODO: Rename to CoverageDiscoverer class Coverage - # @param [String] settings_id + # @param [String] testsuite_path def initialize(testsuite_path) unless File.directory?(testsuite_path) raise ArgumentError, "Not a valid directory: #{testsuite_path}" diff --git a/src/testup/coverage_discoverer.rb b/src/testup/coverage_discoverer.rb index 01558f4..ab002c6 100644 --- a/src/testup/coverage_discoverer.rb +++ b/src/testup/coverage_discoverer.rb @@ -25,7 +25,7 @@ def report(discovered_suite) private - # @param [Array] expected + # @param [Array] expected_test_case # @param [Array] missing # @return [Float] def compute_percentage(expected_test_case, missing) diff --git a/src/testup/log.rb b/src/testup/log.rb index 742bf7a..68e779b 100644 --- a/src/testup/log.rb +++ b/src/testup/log.rb @@ -31,7 +31,7 @@ def self.set_tracing(category, enabled) end # @param [Symbol] category - # @param [Boolean] + # @return [Boolean] def self.tracing(category) @trace[category] || false end diff --git a/src/testup/manifest.rb b/src/testup/manifest.rb index 7c9318e..1e20e52 100644 --- a/src/testup/manifest.rb +++ b/src/testup/manifest.rb @@ -13,7 +13,7 @@ class Manifest attr_reader :filename - # @param [String] filename + # @param [String] manifest_filename def initialize(manifest_filename) @filename = manifest_filename @expected = parse_manifest(manifest_filename) diff --git a/src/testup/report/collection.rb b/src/testup/report/collection.rb index 379d262..e5114dd 100644 --- a/src/testup/report/collection.rb +++ b/src/testup/report/collection.rb @@ -17,7 +17,7 @@ module TestUp module Report class Collection < SortedSet - # @param [Integer, #hash] + # @param [Integer, #hash] value def [](value) # return @hash.keys[value] if value.is_a?(Integer) return each.to_a[value] if value.is_a?(Integer) diff --git a/src/testup/report/test.rb b/src/testup/report/test.rb index 0a2abd5..57f8fde 100644 --- a/src/testup/report/test.rb +++ b/src/testup/report/test.rb @@ -47,7 +47,7 @@ def hash @id.hash end - # @param [Report::Test] + # @param [Report::Test] test # @return [Boolean] def merge_result(test) return false if test.result.nil? diff --git a/src/testup/report/test_coverage.rb b/src/testup/report/test_coverage.rb index c1454dc..a2cc2f7 100644 --- a/src/testup/report/test_coverage.rb +++ b/src/testup/report/test_coverage.rb @@ -27,7 +27,7 @@ def self.from_hash(hash) end # @param [Float] percent - # @param [Hash, Array] + # @param [Hash, Array] missing def initialize(percent, missing) @percent = percent.to_f @missing = restructure(missing) diff --git a/src/testup/report/test_suite.rb b/src/testup/report/test_suite.rb index ebeb693..385f219 100644 --- a/src/testup/report/test_suite.rb +++ b/src/testup/report/test_suite.rb @@ -93,14 +93,14 @@ def rediscover(other_test_suite) self end - # @param [Report::TestCase, Symbol, String] + # @param [Report::TestCase, Symbol, String] test_case # @return [Report::TestCase] def test_case(test_case) @test_cases[test_case] end alias_method :[], :test_case - # @param [Report::TestCase, String] + # @param [Report::TestCase, String] test_case def test_case?(test_case) !test_case(test_case).nil? end diff --git a/src/testup/sketchup_test_utilities.rb b/src/testup/sketchup_test_utilities.rb index aa257fb..820c353 100644 --- a/src/testup/sketchup_test_utilities.rb +++ b/src/testup/sketchup_test_utilities.rb @@ -334,7 +334,7 @@ def assert_no_notification end # @param [String] event - # @param [Integer] argument + # @param [Integer] argument_index # @param [Class] type # @param [Object] expected def assert_callback_data(event, argument_index, type, expected) diff --git a/src/testup/test_discoverer.rb b/src/testup/test_discoverer.rb index 1823c68..28d6d9c 100644 --- a/src/testup/test_discoverer.rb +++ b/src/testup/test_discoverer.rb @@ -116,7 +116,7 @@ def discover_testcases(testsuite_path) } end - # @param [Array] testsuite_paths + # @param [Array] testsuite_path # @return [Array] Path to all test case files found. def discover_testcase_source_files(testsuite_path) # Log.debug ">>> #{self.class}.discover_testcase_source_files(...)" diff --git a/src/testup/ui/runner.rb b/src/testup/ui/runner.rb index 8f4f210..8e1857d 100644 --- a/src/testup/ui/runner.rb +++ b/src/testup/ui/runner.rb @@ -225,7 +225,7 @@ def discover_tests nil end - # @param [Report::TestSuite] test_suite + # @param [Report::TestSuite] test_suites # @return [nil] def rediscover_tests(test_suites) Log.trace :discover, "rediscover_tests(...)" From 51ac9ac186ee967a8df94f2a1ff1a82c9d0617a7 Mon Sep 17 00:00:00 2001 From: Thomas Thomassen Date: Tue, 27 Feb 2024 11:39:53 +0100 Subject: [PATCH 2/3] Fix how the GUI option is propagated. --- src/testup/minitest_plugins/minitest/testup_plugin.rb | 3 ++- src/testup/ui/runner.rb | 7 +++++-- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/src/testup/minitest_plugins/minitest/testup_plugin.rb b/src/testup/minitest_plugins/minitest/testup_plugin.rb index 36c50c0..897c832 100644 --- a/src/testup/minitest_plugins/minitest/testup_plugin.rb +++ b/src/testup/minitest_plugins/minitest/testup_plugin.rb @@ -30,9 +30,10 @@ def self.plugin_testup_options opts, options # :nodoc: end end + # @param [Hash] options Options provided by {.plugin_testup_options} def self.plugin_testup_init(options) TestUp::Log.trace :minitest, 'Minitest TestUp Extension loading...' - if TestUp.settings[:run_in_gui] + if options[:testup_gui] TestUp::Log.trace :minitest, 'Minitest TestUp Extension in GUI mode' # Disable the default reporters as otherwise they'll print lots of data to # the console while the test runs. No need for that. diff --git a/src/testup/ui/runner.rb b/src/testup/ui/runner.rb index 8e1857d..f506d5d 100644 --- a/src/testup/ui/runner.rb +++ b/src/testup/ui/runner.rb @@ -116,7 +116,9 @@ def event_window_ready # @param [Hash] test_suite_json JSON data from JavaScript side. def event_run_tests(test_suite_json) Log.trace :callback, 'event_run_tests(...)' - options = {} + options = { + ui: TestUp.settings[:run_in_gui], + } test_suite = Report::TestSuite.from_hash(test_suite_json) TestUp::API.run_test_suite(test_suite, options: options) { |results| test_suite.merge_results(results) @@ -131,7 +133,8 @@ def event_rerun_tests return unless run_file run_config = TestUp::Runs.read_config(run_file) options = { - seed: run_config[:seed] + seed: run_config[:seed], + ui: TestUp.settings[:run_in_gui], } tests = run_config[:tests] title = run_config[:test_suite] From b4de26d871c0aea00bd975b75904ecdcab15e94d Mon Sep 17 00:00:00 2001 From: Thomas Thomassen Date: Tue, 27 Feb 2024 11:40:13 +0100 Subject: [PATCH 3/3] Update documentation for the API options. --- src/testup/api.rb | 23 +++++++++++++++++++---- src/testup/test_runner.rb | 15 +++++++++++++++ 2 files changed, 34 insertions(+), 4 deletions(-) diff --git a/src/testup/api.rb b/src/testup/api.rb index 59943d5..e4d081f 100644 --- a/src/testup/api.rb +++ b/src/testup/api.rb @@ -1,6 +1,6 @@ #------------------------------------------------------------------------------- # -# Copyright 2013-2018 Trimble Inc. +# Copyright 2013-2024 Trimble Inc. # License: The MIT License (MIT) # #------------------------------------------------------------------------------- @@ -27,6 +27,10 @@ module API # # @param [TestUp::Report::TestSuite, Pathname, String] test_suite # @param [Hash] config + # @option config [String] 'Seed' Integer numeric for the Minitest random seed. + # @option config [String] 'Verbose' Turns on verbose reporting if key is present. + # @option config [String] 'Output' JSON file to output results to. + # @option config [Array] 'Tests' def self.run_suite_without_gui(test_suite, config = {}) test_suite_path = if test_suite.is_a?(TestUp::Report::TestSuite) Pathname.new(test_suite.path) @@ -70,22 +74,33 @@ def self.run_suite_without_gui(test_suite, config = {}) end # @example Run a test case: - # TestUp.run_tests(["TC_Sketchup_Edge#"]) + # TestUp::API.run_tests(["TC_Sketchup_Edge#"], path: path) # # @example Run single test: - # TestUp.run_tests(["TC_Sketchup_Edge#start"]) + # TestUp::API.run_tests(["TC_Sketchup_Edge#start"], path: path) # # @example Run a set of test cases and/or tests: # tests = [ # "TC_Sketchup_Face#", # "TC_Sketchup_Edge#start", "TC_Sketchup_Edge#end" # ] - # TestUp.run_tests(tests) + # path = "path/to/testsuite/" + # TestUp::API.run_tests(tests, path: path) + # + # @todo The `path` parameter is not optional. + # @todo The `title` parameter should be extracted from the path. # # @param [Array] tests list of tests or test cases to run. # @param [String] title Name of test_suite # @param [String] path Path to the test_suite # @param [Hash] options + # @option options [Boolean] :show_console Open the Ruby Console before running tests. + # @option options [Boolean] :clear_console Clear the Ruby Console before running tests. + # @option options [Boolean] :ci Generate JSON report to STDOUT. + # @option options [String] :ci_out Pipe JSON report to file. + # @option options [Boolean] :ui Update the TestUp dialog. + # @option options [Integer] :seed Set the randomization seed for Minitest. + # @option options [Boolean] :verbose # @yield [Report::TestSuite] # @return [Boolean] def self.run_tests(tests, title: 'Untitled', path: nil, options: {}) diff --git a/src/testup/test_runner.rb b/src/testup/test_runner.rb index fdeae42..410997c 100644 --- a/src/testup/test_runner.rb +++ b/src/testup/test_runner.rb @@ -25,6 +25,11 @@ def initialize(title: 'Untitled', path: nil) # @param [Array] tests # @param [Hash] options + # @option options [Boolean] :ci Generate JSON report to STDOUT. + # @option options [String] :ci_out Pipe JSON report to file. + # @option options [Boolean] :ui Update the TestUp dialog. + # @option options [Integer] :seed Set the randomization seed for Minitest. + # @option options [Boolean] :verbose # @yield [Array] # return [Boolean] def run(tests, options = {}) @@ -40,6 +45,11 @@ def run(tests, options = {}) # @param [Array] tests # @param [Hash] options + # @option options [Boolean] :ci Generate JSON report to STDOUT. + # @option options [String] :ci_out Pipe JSON report to file. + # @option options [Boolean] :ui Update the TestUp dialog. + # @option options [Integer] :seed Set the randomization seed for Minitest. + # @option options [Boolean] :verbose # return [nil] def run_tests(tests, options) TestUp::FileReporter.set_run_info(@title, @path) # Hack! @@ -64,6 +74,11 @@ def run_tests(tests, options) # @param [Array] tests # @param [Hash] options + # @option options [Boolean] :ci Generate JSON report to STDOUT. + # @option options [String] :ci_out Pipe JSON report to file. + # @option options [Boolean] :ui Update the TestUp dialog. + # @option options [Integer] :seed Set the randomization seed for Minitest. + # @option options [Boolean] :verbose # return [Array] def minitest_arguments(tests, options) arguments = []