minitap 0.5.3 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,127 @@
1
+ # Details
2
+
3
+ ## Skipped tests
4
+
5
+ Given a test file:
6
+
7
+ require 'minitest/autorun'
8
+ require 'minitap'
9
+
10
+ class ExampleTest < Minitest::Test
11
+ def test_skipped
12
+ skip "not today"
13
+ end
14
+
15
+ def test_passing
16
+ assert true
17
+ end
18
+ end
19
+
20
+ A skipped test has the status `omit`, which is what TAP-Y/J calls it,
21
+ and gives the reason.
22
+
23
+ stream = run_tapy('--tapy')
24
+ tests = tests(stream)
25
+
26
+ tests['test_skipped']['status'] #=> 'omit'
27
+ tests['test_skipped']['exception']['message'] #=> 'not today'
28
+ tests['test_skipped']['exception']['file'] #=> 'test.rb'
29
+ tests['test_skipped']['exception']['line'] #=> 6
30
+
31
+ stream.last['counts'] #=> {'total'=>2, 'pass'=>1, 'fail'=>0, 'error'=>0, 'omit'=>1, 'todo'=>0}
32
+
33
+ A skip is not a failure.
34
+
35
+ @status.success? #=> true
36
+
37
+ ## Output from tests
38
+
39
+ Given a test file:
40
+
41
+ require 'minitest/autorun'
42
+ require 'minitap'
43
+
44
+ class ExampleTest < Minitest::Test
45
+ def test_noisy
46
+ puts "to stdout"
47
+ warn "to stderr"
48
+ assert true
49
+ end
50
+
51
+ def test_quiet
52
+ assert true
53
+ end
54
+ end
55
+
56
+ What a test prints would break the stream. It is captured and becomes
57
+ part of the test's record.
58
+
59
+ stream = run_tapy('--tapy')
60
+ tests = tests(stream)
61
+
62
+ tests['test_noisy']['stdout'] #=> "to stdout\n"
63
+ tests['test_noisy']['stderr'] #=> "to stderr\n"
64
+
65
+ tests['test_quiet'].key?('stdout') #=> false
66
+ tests['test_quiet'].key?('stderr') #=> false
67
+
68
+ @stderr #=> ''
69
+
70
+ ## Several classes
71
+
72
+ Given a test file:
73
+
74
+ require 'minitest/autorun'
75
+ require 'minitap'
76
+
77
+ class FirstTest < Minitest::Test
78
+ def test_one; assert true; end
79
+ def test_two; assert true; end
80
+ end
81
+
82
+ class SecondTest < Minitest::Test
83
+ def test_three; assert true; end
84
+ end
85
+
86
+ Each class is a case, followed by its tests.
87
+
88
+ stream = run_tapy('--tapy')
89
+
90
+ cases = stream.select { |d| d['type'] == 'case' }.map { |d| d['label'] }
91
+
92
+ cases.sort #=> ['FirstTest', 'SecondTest']
93
+
94
+ types = stream.map { |d| d['type'] }
95
+ index = stream.index { |d| d['label'] == 'FirstTest' }
96
+
97
+ types[index, 3] #=> ['case', 'test', 'test']
98
+
99
+ stream.first['count'] #=> 3
100
+
101
+ ## Selecting tests by name
102
+
103
+ The count at the start of the stream is of the tests that will run,
104
+ so it follows Minitest's `--name` option.
105
+
106
+ stream = run_tapy('--tapy', '--name', '/one|three/')
107
+
108
+ stream.first['count'] #=> 2
109
+ stream.last['counts']['total'] #=> 2
110
+
111
+ tests(stream).keys.sort #=> ['test_one', 'test_three']
112
+
113
+ ## The seed
114
+
115
+ The seed is in the `suite` document, and the tests run in the order
116
+ that seed gives them without Minitap.
117
+
118
+ stream = run_tapy('--tapy', '--seed', '42')
119
+
120
+ stream.first['seed'] #=> 42
121
+
122
+ with = stream.select { |d| d['type'] == 'test' }.map { |d| d['label'] }
123
+
124
+ plain = run_tests('--seed', '42', '--verbose')
125
+ without = plain.scan(/^\w+Test#(test_\w+)/).flatten
126
+
127
+ with #=> without
data/demo/06_tapout.md ADDED
@@ -0,0 +1,44 @@
1
+ # Tapout
2
+
3
+ The stream is for Tapout, which renders it in a format of your choice.
4
+
5
+ Given a test file:
6
+
7
+ require 'minitest/autorun'
8
+ require 'minitap'
9
+
10
+ class ExampleTest < Minitest::Test
11
+ def test_error
12
+ raise "boom"
13
+ end
14
+
15
+ def test_failing
16
+ assert_equal('1', '2')
17
+ end
18
+
19
+ def test_passing
20
+ assert_equal('1', '1')
21
+ end
22
+
23
+ def test_skipped
24
+ skip "not today"
25
+ end
26
+ end
27
+
28
+ Tapout reads the TAP-Y stream.
29
+
30
+ out = tapout(run_tests('--tapy', '--seed', '1'), 'tap')
31
+
32
+ out.assert.include?('1..4')
33
+ out.assert =~ /^ok \d - test_passing$/
34
+ out.assert =~ /^not ok \d - test_failing$/
35
+ out.assert =~ /^not ok \d - test_error$/
36
+ out.assert =~ /^ok \d - test_skipped # SKIP not today$/
37
+
38
+ And the TAP-J stream.
39
+
40
+ out = tapout(run_tests('--tapj', '--seed', '1'), 'tap')
41
+
42
+ out.assert =~ /^ok \d - test_passing$/
43
+ out.assert =~ /^not ok \d - test_failing$/
44
+ out.assert =~ /^ok \d - test_skipped # SKIP not today$/
@@ -0,0 +1 @@
1
+ require 'ae'
@@ -0,0 +1,48 @@
1
+ require 'minitest'
2
+ require 'tmpdir'
3
+ require 'open3'
4
+ require 'rbconfig'
5
+ require 'yaml'
6
+ require 'json'
7
+
8
+ # Each demo writes a test file and runs it in a process of its own,
9
+ # the way a test suite is run.
10
+
11
+ LIB = File.expand_path('../../lib', __dir__)
12
+
13
+ When 'iven a test file' do |text|
14
+ @source = text
15
+ end
16
+
17
+ # Run the test file with the given command line options. Returns what
18
+ # the run wrote to standard output.
19
+ def run_tests(*options)
20
+ Dir.mktmpdir('minitap') do |dir|
21
+ File.write(File.join(dir, 'test.rb'), @source)
22
+ command = [RbConfig.ruby, "-I#{LIB}", 'test.rb', *options]
23
+ @stdout, @stderr, @status = Open3.capture3(*command, :chdir => dir)
24
+ end
25
+ @stdout
26
+ end
27
+
28
+ # Run the test file and read its output as a TAP-Y stream.
29
+ def run_tapy(*options)
30
+ YAML.load_stream(run_tests(*options))
31
+ end
32
+
33
+ # Run the test file and read its output as a TAP-J stream.
34
+ def run_tapj(*options)
35
+ run_tests(*options).lines.map { |line| JSON.parse(line) }
36
+ end
37
+
38
+ # The test records of a stream, by label.
39
+ def tests(stream)
40
+ stream.select { |d| d['type'] == 'test' }.to_h { |d| [d['label'], d] }
41
+ end
42
+
43
+ # Pipe a stream through Tapout. Returns what Tapout printed.
44
+ def tapout(stream, reporter)
45
+ bin = Gem.bin_path('tapout', 'tapout')
46
+ out, _ = Open3.capture2(RbConfig.ruby, bin, reporter, :stdin_data => stream)
47
+ out
48
+ end
@@ -1,8 +1,7 @@
1
+ # Run the tests when the program exits, reporting in TAP-Y unless
2
+ # another format has been chosen.
3
+
1
4
  require 'minitest/autorun'
2
5
  require 'minitap'
3
6
 
4
- # Default it TapY.
5
- #Minitest.reporter = Minitest::TapJ
6
- Minitest.reporter = Minitest::TapY
7
-
8
-
7
+ Minitap.tapy! unless Minitap.format
@@ -0,0 +1,294 @@
1
+ require 'minitest'
2
+ require 'stringio'
3
+
4
+ module Minitap
5
+
6
+ # Base class of the TAP-Y and TAP-J reporters. It turns Minitest's
7
+ # results into the records of a TAP-Y/J stream; the subclasses write
8
+ # them out.
9
+ #
10
+ # While tests run, `$stdout` and `$stderr` are captured, so that
11
+ # what a test prints becomes part of its record instead of breaking
12
+ # the stream.
13
+ class Reporter < Minitest::StatisticsReporter
14
+
15
+ # TAP-Y/J revision.
16
+ REVISION = 4
17
+
18
+ # Number of lines of source to show on each side of a failure.
19
+ SNIPPET_RADIUS = 2
20
+
21
+ # Where Minitap's own code lives, to keep it out of backtraces.
22
+ LIB_DIRECTORY = File.expand_path('..', __dir__) + File::SEPARATOR
23
+
24
+ def initialize(io = $stdout, options = {})
25
+ super
26
+ # Tapout reads from a pipe, so nothing should wait in a buffer.
27
+ io.sync = true if io.respond_to?(:sync=)
28
+ @source_cache = {}
29
+ @current_case = nil
30
+ end
31
+
32
+ # Minitest calls this just before the tests run.
33
+ def start
34
+ super
35
+ @suite_start = Time.now
36
+ capture_io
37
+ emit suite_record
38
+ end
39
+
40
+ # Minitest calls this with the result of each test.
41
+ def record(result)
42
+ super
43
+ test_case = case_name(result)
44
+ if test_case != @current_case
45
+ @current_case = test_case
46
+ emit case_record(test_case)
47
+ end
48
+ emit test_record(result)
49
+ end
50
+
51
+ # Minitest calls this when all tests have run.
52
+ def report
53
+ super
54
+ release_io
55
+ emit final_record
56
+ finish
57
+ end
58
+
59
+ private
60
+
61
+ # Write a record to the stream. Subclasses define this.
62
+ def emit(record)
63
+ raise NotImplementedError
64
+ end
65
+
66
+ # Write whatever ends the stream.
67
+ def finish
68
+ end
69
+
70
+ #
71
+ def suite_record
72
+ {
73
+ 'type' => 'suite',
74
+ 'start' => @suite_start.strftime('%Y-%m-%d %H:%M:%S'),
75
+ 'count' => test_count,
76
+ 'seed' => options[:seed],
77
+ 'rev' => REVISION
78
+ }
79
+ end
80
+
81
+ #
82
+ def case_record(test_case)
83
+ {
84
+ 'type' => 'case',
85
+ 'label' => test_case.to_s,
86
+ 'level' => 0
87
+ }
88
+ end
89
+
90
+ #
91
+ def test_record(result)
92
+ failure = result.failure
93
+
94
+ record = {
95
+ 'type' => 'test',
96
+ 'status' => status(failure),
97
+ 'label' => label(result)
98
+ }
99
+ record['exception'] = exception_record(failure) if failure
100
+
101
+ stdout, stderr = captured_output
102
+ record['stdout'] = stdout unless stdout.empty?
103
+ record['stderr'] = stderr unless stderr.empty?
104
+
105
+ record['time'] = Time.now - @suite_start
106
+ record
107
+ end
108
+
109
+ #
110
+ def final_record
111
+ {
112
+ 'type' => 'final',
113
+ 'time' => Time.now - @suite_start,
114
+ 'counts' => {
115
+ 'total' => count,
116
+ 'pass' => count - failures - errors - skips,
117
+ 'fail' => failures,
118
+ 'error' => errors,
119
+ 'omit' => skips,
120
+ 'todo' => 0
121
+ }
122
+ }
123
+ end
124
+
125
+ # TAP-Y/J calls a skipped test omitted.
126
+ def status(failure)
127
+ case failure
128
+ when nil then 'pass'
129
+ when Minitest::UnexpectedError then 'error'
130
+ when Minitest::Skip then 'omit'
131
+ else 'fail'
132
+ end
133
+ end
134
+
135
+ # The name of the test. Minitest::Spec names a test
136
+ # `test_0001_does something`; the label is the part that was written.
137
+ def label(result)
138
+ result.name.to_s.sub(/\Atest_\d{4}_/, '')
139
+ end
140
+
141
+ # The name of the class the test belongs to.
142
+ def case_name(result)
143
+ result.respond_to?(:klass) ? result.klass.to_s : result.class.name
144
+ end
145
+
146
+ #
147
+ def exception_record(failure)
148
+ error = actual_error(failure)
149
+ backtrace = clean_backtrace(failure.backtrace || error.backtrace)
150
+ file, line = location(backtrace)
151
+
152
+ record = { 'message' => error.message.to_s.strip, 'class' => error.class.name }
153
+
154
+ if file
155
+ record['file'] = file
156
+ record['line'] = line
157
+ if lines = source(file)
158
+ record['source'] = lines[line - 1].to_s.strip
159
+ record['snippet'] = snippet(lines, line)
160
+ end
161
+ end
162
+
163
+ record['backtrace'] = backtrace
164
+ record
165
+ end
166
+
167
+ # Minitest wraps an error raised by a test in an UnexpectedError.
168
+ def actual_error(failure)
169
+ return failure unless Minitest::UnexpectedError === failure
170
+ failure.respond_to?(:error) ? failure.error : failure.exception
171
+ end
172
+
173
+ # The backtrace without the test framework, without the method
174
+ # names, and with paths relative to the working directory.
175
+ def clean_backtrace(backtrace)
176
+ trace = Minitest.filter_backtrace(Array(backtrace))
177
+ trace = trace.reject { |line| line.start_with?(LIB_DIRECTORY) }
178
+ trace.map do |line|
179
+ line.sub(/:in .*\z/m, '').sub(Dir.pwd + File::SEPARATOR, '')
180
+ end
181
+ end
182
+
183
+ # File and line number of the first line of a backtrace.
184
+ def location(backtrace)
185
+ md = /\A(.+?):(\d+)\z/.match(backtrace.first.to_s)
186
+ md ? [md[1], md[2].to_i] : [nil, nil]
187
+ end
188
+
189
+ # The lines of a source file, or nil if it can't be read.
190
+ def source(file)
191
+ return @source_cache[file] if @source_cache.key?(file)
192
+ @source_cache[file] = File.file?(file) ? File.readlines(file) : nil
193
+ end
194
+
195
+ # The lines around a line of source, as a list of number => text.
196
+ def snippet(lines, line)
197
+ first = [line - SNIPPET_RADIUS, 1].max
198
+ last = [line + SNIPPET_RADIUS, lines.size].min
199
+ (first..last).map { |n| { n => lines[n - 1].chomp } }
200
+ end
201
+
202
+ # How many tests are about to run.
203
+ #
204
+ # Asking a class for its tests shuffles them, which draws on Ruby's
205
+ # random numbers. So they are seeded again afterwards, and the tests
206
+ # run in the order they would have without Minitap.
207
+ def test_count
208
+ total = Minitest::Runnable.runnables.inject(0) do |sum, runnable|
209
+ sum + selected_methods(runnable).size
210
+ end
211
+ srand options[:seed] if options[:seed]
212
+ total
213
+ end
214
+
215
+ # The tests of a class that Minitest's name options select. The
216
+ # option is `:include` in Minitest 6 and `:filter` before.
217
+ def selected_methods(runnable)
218
+ methods = runnable.runnable_methods
219
+ wanted = name_pattern(options[:include] || options[:filter])
220
+ spurned = name_pattern(options[:exclude])
221
+ methods = methods.select { |m| wanted === m || wanted === "#{runnable}##{m}" } if wanted
222
+ methods = methods.reject { |m| spurned === m || spurned === "#{runnable}##{m}" } if spurned
223
+ methods
224
+ rescue NotImplementedError
225
+ []
226
+ end
227
+
228
+ # A name option written `/like this/` is a regular expression.
229
+ def name_pattern(pattern)
230
+ String === pattern && pattern =~ %r{/(.*)/} ? Regexp.new($1) : pattern
231
+ end
232
+
233
+ #
234
+ def capture_io
235
+ @real_stdout, @real_stderr = $stdout, $stderr
236
+ @stdout, @stderr = StringIO.new, StringIO.new
237
+ $stdout, $stderr = @stdout, @stderr
238
+ end
239
+
240
+ #
241
+ def release_io
242
+ $stdout = @real_stdout if $stdout.equal?(@stdout)
243
+ $stderr = @real_stderr if $stderr.equal?(@stderr)
244
+ end
245
+
246
+ # What has been printed since the last record, as two strings.
247
+ def captured_output
248
+ [@stdout, @stderr].map do |capture|
249
+ text = capture.string.dup
250
+ capture.truncate(0)
251
+ capture.rewind
252
+ text
253
+ end
254
+ end
255
+
256
+ end
257
+
258
+ # Reports in TAP-Y, a stream of YAML documents.
259
+ class TapY < Reporter
260
+
261
+ def initialize(io = $stdout, options = {})
262
+ require 'yaml'
263
+ super
264
+ end
265
+
266
+ private
267
+
268
+ def emit(record)
269
+ io.puts record.to_yaml
270
+ end
271
+
272
+ def finish
273
+ io.puts '...'
274
+ end
275
+
276
+ end
277
+
278
+ # Reports in TAP-J, a JSON document on each line.
279
+ class TapJ < Reporter
280
+
281
+ def initialize(io = $stdout, options = {})
282
+ require 'json'
283
+ super
284
+ end
285
+
286
+ private
287
+
288
+ def emit(record)
289
+ io.puts JSON.generate(record)
290
+ end
291
+
292
+ end
293
+
294
+ end
@@ -0,0 +1,3 @@
1
+ module Minitap
2
+ VERSION = '0.6.0'
3
+ end
data/lib/minitap.rb CHANGED
@@ -1,11 +1,91 @@
1
- #gem "minitest", "~> 5.0"
2
-
3
1
  require 'minitest'
4
- require 'minitest/reporter_api'
5
- require 'minitap/minitest5'
2
+ require 'minitap/version'
3
+ require 'minitap/reporter'
6
4
 
5
+ # Minitap makes Minitest report in TAP-Y or TAP-J, the formats that
6
+ # Tapout reads. It is a Minitest plugin.
7
+ #
8
+ # Choose the format on the command line, with `--tapy` or `--tapj`, or
9
+ # in a test helper:
10
+ #
11
+ # require 'minitest/autorun'
12
+ # require 'minitap'
13
+ #
14
+ # Minitap.tapy!
15
+ #
7
16
  module Minitap
8
- TapY = Minitest::TapY
9
- TapJ = Minitest::TapJ
10
- end
11
17
 
18
+ # The reporter for each format, by the format's name.
19
+ FORMATS = { 'tapy' => TapY, 'tapj' => TapJ }
20
+
21
+ @format = nil
22
+ @registered = false
23
+
24
+ class << self
25
+
26
+ # The format chosen in code, 'tapy' or 'tapj', or nil. A `--tapy`
27
+ # or `--tapj` option on the command line takes precedence over it.
28
+ attr_reader :format
29
+
30
+ # Choose the format: :tapy, :tapj, or nil for Minitest's own report.
31
+ def format=(name)
32
+ name = name.to_s.downcase.delete('-_') unless name.nil?
33
+ unless name.nil? || FORMATS.key?(name)
34
+ raise ArgumentError, "unknown format #{name.inspect}, use :tapy or :tapj"
35
+ end
36
+ @format = name
37
+ end
38
+
39
+ # Report in TAP-Y.
40
+ def tapy!
41
+ self.format = :tapy
42
+ end
43
+
44
+ # Report in TAP-J.
45
+ def tapj!
46
+ self.format = :tapj
47
+ end
48
+
49
+ # Called by Minitest to add this plugin's command line options.
50
+ def minitest_plugin_options(opts, options)
51
+ opts.on '--tapy', 'Report in TAP-Y, for Tapout.' do
52
+ options[:minitap] = 'tapy'
53
+ end
54
+ opts.on '--tapj', 'Report in TAP-J, for Tapout.' do
55
+ options[:minitap] = 'tapj'
56
+ end
57
+ end
58
+
59
+ # Called by Minitest as a run starts. If a format was chosen, its
60
+ # reporter takes the place of Minitest's own reporters, whose
61
+ # output would corrupt the stream.
62
+ def minitest_plugin_init(options)
63
+ format = options[:minitap] || self.format
64
+ return unless format
65
+
66
+ composite = Minitest.reporter
67
+ return if composite.reporters.any? { |r| Reporter === r }
68
+
69
+ composite.reporters.clear
70
+ composite << FORMATS.fetch(format.to_s).new(options[:io], options)
71
+ end
72
+
73
+ # Has Minitap been registered with Minitest as a plugin module?
74
+ def registered?
75
+ @registered
76
+ end
77
+
78
+ # Register with Minitest. Minitest 5.24 and newer take a module.
79
+ # Older versions find `minitest/minitap_plugin.rb` on their own.
80
+ def register
81
+ return if registered?
82
+ return unless Minitest.respond_to?(:register_plugin)
83
+ Minitest.register_plugin(self)
84
+ @registered = true
85
+ end
86
+
87
+ end
88
+
89
+ register
90
+
91
+ end
@@ -1,40 +1,20 @@
1
- module Minitest
1
+ # Minitest finds this file by its name. Minitest 5 loads it on its own
2
+ # when the gem is installed; `Minitest.load :minitap` loads it too.
3
+ #
4
+ # Requiring `minitap` registers the plugin as a module where Minitest
5
+ # supports that (5.24 and newer). The methods below are for older
6
+ # versions, which only know plugins by name.
2
7
 
3
- #
4
- def self.plugin_minitap_options(opts, options)
5
- opts.on "--tapy", "Use TapY reporter." do
6
- options[:minitap] = 'tapy'
7
- end
8
+ require 'minitap'
8
9
 
9
- opts.on "--tapj", "Use TapJ reporter." do
10
- options[:minitap] = 'tapj'
11
- end
10
+ module Minitest
12
11
 
13
- # DEPRECATED Thanks to minitest-reporter-api gem.
14
- #unless options[:minitap]
15
- # if defined?(Minitest::TapY) && self.reporter == Minitest::TapY
16
- # options[:minitap] = 'tapy'
17
- # elsif defined?(Minitest::TapJ) && self.reporter == Minitest::TapJ
18
- # options[:minitap] = 'tapj'
19
- # end
20
- #end
12
+ def self.plugin_minitap_options(opts, options)
13
+ Minitap.minitest_plugin_options(opts, options) unless Minitap.registered?
21
14
  end
22
15
 
23
- #
24
16
  def self.plugin_minitap_init(options)
25
- if options[:minitap]
26
- require 'minitap/minitest5'
27
-
28
- self.reporter.reporters.clear
29
-
30
- case options[:minitap] || ENV['rpt']
31
- when 'tapj'
32
- self.reporter << TapJ.new(options)
33
- when 'tapy'
34
- self.reporter << TapY.new(options)
35
- end
36
- end
17
+ Minitap.minitest_plugin_init(options) unless Minitap.registered?
37
18
  end
38
19
 
39
20
  end
40
-