README.md in minitest_log-0.2.0 vs README.md in minitest_log-1.0.0
- old
+ new
@@ -1,16 +1,21 @@
-[](https://badge.fury.io/rb/minitest_log)
-
# MinitestLog
+[](https://badge.fury.io/rb/minitest_log)
```MinitestLog``` gives you three things:
- **Nested sections:** Use nested sections to structure your test (and, importantly, its log), so that the test can "tell its story" clearly.
-- **Data explication:** Use data-logging methods to log objects. Most collections (```Aray```, ```Hash```, etc.) are automatically logged in detail.
+- **Data explication:** Use data-logging methods to log objects. Most collections (```Array```, ```Hash```, etc.) are automatically logged in detail.
- **(And of course) Verdicts:** Use verdict methods to express assertions. Details for the verdict are logged, whether passed or failed.
+## Installation
+
+```sh
+gem install minitest_log
+```
+
## Contents
- [Logs and Sections](#logs-and-sections)
- [Nested Sections](#nested-sections)
- [Text](#text)
- [Formatted Text](#formatted-text)
@@ -23,10 +28,11 @@
- [Options](#options)
- [Root Name](#root-name)
- [XML Indentation](#xml-indentation)
- [Summary](#summary)
- [Error Verdict](#error-verdict)
+ - [Backtrace Filter](#backtrace-filter)
- [Data](#data)
- [Strings](#strings)
- [Hash-Like Objects](#hash-like-objects)
- [Array-Like Objects](#array-like-objects)
- [Other Objects](#other-objects)
@@ -67,10 +73,12 @@
- [verdict_refute_same?](#verdict_refute_same)
- [Tips](#tips)
- [Use Short Verdict Aliases](#use-short-verdict-aliases)
- [Avoid Failure Clutter](#avoid-failure-clutter)
- [Facilitate Post-Processing](#facilitate-post-processing)
+- [Oh, and Tests](#oh-and-tests)
+- [About This README](#about-this-readme)
## Logs and Sections
### Nested Sections
@@ -276,17 +284,17 @@
```
```log.xml```:
```xml
<log>
- <section_ name='My section with timestamp' timestamp='2019-05-07-Tue-10.58.13.155'>
+ <section_ name='My section with timestamp' timestamp='2019-05-09-Thu-10.32.53.066'>
Section with timestamp.
</section_>
<section_ name='My section with duration' duration_seconds='0.501'>
Section with duration.
</section_>
- <section_ name='My section with both' timestamp='2019-05-07-Tue-10.58.13.656' duration_seconds='0.500'>
+ <section_ name='My section with both' timestamp='2019-05-09-Thu-10.32.53.568' duration_seconds='0.501'>
Section with both.
</section_>
</log>
```
@@ -354,11 +362,11 @@
```log.xml```:
```xml
<log>
<section_ name='My unrescued section'>
- <uncaught_exception_ timestamp='2019-05-07-Tue-10.58.14.602' class='RuntimeError'>
+ <uncaught_exception_ timestamp='2019-05-09-Thu-10.32.54.471' class='RuntimeError'>
<message_>
Boo!
</message_>
<backtrace_>
<![CDATA[
@@ -411,11 +419,11 @@
```
```log.xml```:
```xml
<log>
- <section_ name='Section with potpourri of arguments' a='0' b='1' timestamp='2019-05-07-Tue-10.58.11.338' c='2' d='3' duration_seconds='0.502'>
+ <section_ name='Section with potpourri of arguments' a='0' b='1' timestamp='2019-05-09-Thu-10.32.51.426' c='2' d='3' duration_seconds='0.501'>
Word More words
<rescued_exception_ class='Exception' message='Boo!'>
<backtrace_>
<![CDATA[
example.rb:17:in `block (2 levels) in test_demo'
@@ -826,11 +834,90 @@
</exception_>
</verdict_>
</log>
```
+#### Backtrace Filter
+By default, a backtrace omits entries containing the token ```minitest```. This keeps the backtrace focussed on your code instead of the gems' code.
+
+Override that behavior by specifying ioption ```:backtrace_filter``` with a ```Regexp``` object. Entries matching that pattern will be omitted from the backtrace.
+
+```backtrace_filter.rb```:
+```ruby
+require 'minitest_log'
+class Test < Minitest::Test
+ def test_demo
+ MinitestLog.new('default_backtrace_filter.xml') do |log|
+ fail 'Boo!'
+ end
+ MinitestLog.new('custom_backtrace_filter.xml', :backtrace_filter => /xxx/) do |log|
+ fail 'Boo!'
+ end
+ end
+end
+```
+
+```default_backtrace_filter.xml```:
+```xml
+<log>
+ <uncaught_exception_ timestamp='2019-05-09-Thu-10.32.49.597' class='RuntimeError'>
+ <message_>
+ Boo!
+ </message_>
+ <backtrace_>
+ <![CDATA[
+backtrace_filter.rb:5:in `block in test_demo'
+backtrace_filter.rb:4:in `new'
+backtrace_filter.rb:4:in `test_demo'
+]]>
+ </backtrace_>
+ </uncaught_exception_>
+</log>
+```
+
+```custom_backtrace_filter.xml```:
+```xml
+<log>
+ <uncaught_exception_ timestamp='2019-05-09-Thu-10.32.49.599' class='RuntimeError'>
+ <message_>
+ Boo!
+ </message_>
+ <backtrace_>
+ <![CDATA[
+backtrace_filter.rb:8:in `block in test_demo'
+C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/minitest_log-0.2.0/lib/minitest_log.rb:59:in `initialize'
+backtrace_filter.rb:7:in `new'
+backtrace_filter.rb:7:in `test_demo'
+C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/minitest-5.11.3/lib/minitest/test.rb:98:in `block (3 levels) in run'
+C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/minitest-5.11.3/lib/minitest/test.rb:195:in `capture_exceptions'
+C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/minitest-5.11.3/lib/minitest/test.rb:95:in `block (2 levels) in run'
+C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/minitest-5.11.3/lib/minitest.rb:265:in `time_it'
+C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/minitest-5.11.3/lib/minitest/test.rb:94:in `block in run'
+C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/minitest-5.11.3/lib/minitest.rb:360:in `on_signal'
+C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/minitest-5.11.3/lib/minitest/test.rb:211:in `with_info_handler'
+C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/minitest-5.11.3/lib/minitest/test.rb:93:in `run'
+C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/minitest-5.11.3/lib/minitest.rb:960:in `run_one_method'
+C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/minitest-5.11.3/lib/minitest.rb:334:in `run_one_method'
+C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/minitest-5.11.3/lib/minitest.rb:321:in `block (2 levels) in run'
+C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/minitest-5.11.3/lib/minitest.rb:320:in `each'
+C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/minitest-5.11.3/lib/minitest.rb:320:in `block in run'
+C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/minitest-5.11.3/lib/minitest.rb:360:in `on_signal'
+C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/minitest-5.11.3/lib/minitest.rb:347:in `with_info_handler'
+C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/minitest-5.11.3/lib/minitest.rb:319:in `run'
+C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/minitest-5.11.3/lib/minitest.rb:159:in `block in __run'
+C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/minitest-5.11.3/lib/minitest.rb:159:in `map'
+C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/minitest-5.11.3/lib/minitest.rb:159:in `__run'
+C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/minitest-5.11.3/lib/minitest.rb:136:in `run'
+C:/Ruby25-x64/lib/ruby/gems/2.5.0/gems/minitest-5.11.3/lib/minitest.rb:63:in `block in autorun'
+]]>
+ </backtrace_>
+ </uncaught_exception_>
+</log>
+```
+
+
## Data
Put data onto the log using method ```:put_data```.
A data object ```obj``` is treated as follows:
@@ -1024,11 +1111,11 @@
</data_>
<data_ name='My regexp' class='Regexp' method=':to_s'>
(?-mix:Bar)
</data_>
<data_ name='My time' class='Time' method=':to_s'>
- 2019-05-07 10:58:07 -0500
+ 2019-05-09 10:32:47 -0500
</data_>
<data_ name='My uri,' class='URI::HTTPS' method=':to_s'>
https://www.github.com
</data_>
</section_>
@@ -1796,11 +1883,11 @@
<actual_ class='Symbol' value=':foo'/>
</verdict_>
<verdict_ method='verdict_assert_same?' outcome='failed' id='another_id' message='Another message'>
<expected_ class='String' value='"foo"'/>
<actual_ class='String' value='"foo"'/>
- <exception_ class='Minitest::Assertion' message='Expected "foo" (oid=27958320) to be the same as "foo" (oid=27958340).'>
+ <exception_ class='Minitest::Assertion' message='Expected "foo" (oid=27933780) to be the same as "foo" (oid=27933800).'>
<backtrace_>
<
+
+## Oh, and Tests
+
+This project's tests generate 135 [logs and other output files](../../tree/master/test/actual), performing 484 verifications.
+
+- [log_test.rb](../../tree/master/test/log_test.rb)
+- [verdict_test.rb](../../tree/master/test/verdict_test.rb)
+
+## About This README
+
+This README page is kept "green" because in addition to the tests, there's a rake task that:
+
+- Executes the [50 example scripts](markdown/readme), capturing their output.
+- Uses file inclusion to assemble this ```README.md``` file.
+
+Shameless plug: GitHub flavored markdown does not support file inclusion, but my Ruby gem [markdown_helper](https://rubygems.org/gems/markdown_helper) does. It's a [GitHub project](https://github.com/BurdetteLamar/markdown_helper#markdown-helper), too.
+