IDE Test Report Plugin updates

- Added mutex for post test fixture event handling
- Made documentation more better

plugins/stdout_ide_tests_report/README.md

@@ -1,15 +1,48 @@
-ceedling-stdout-ide-tests-report
-================================
+# Ceedling Plugin: IDE Tests Report
 
-## Overview
+# Overview
 
-The stdout_ide_tests_report replaces the normal ceedling "pretty" output with 
-a simplified variant intended to be easily parseable.
+This plugin is intended to be used in place of the more commonly used "pretty" 
+test report plugin. Like its sibling, this plugin ollects raw test results from
+the individual test executables of your test suite and presents them in a more 
+readable summary form.
 
-## Setup
+The format of test results produced by this plugin is identical to its prettier
+sibling with one key difference — test failures are listed in such a way that 
+filepaths, line numbers, and test case function names can be easily parsed by 
+a typical IDE. The formatting of test failure messages uses a simple, defacto 
+standard of a sort recognized almost universally.
 
-Enable the plugin in your project.yml by adding `stdout_ide_tests_report`
-to the list of enabled plugins.
+The end result is that test failures in your IDE's build window can become 
+links that jump directly to failing test cases.
+
+# Example Output
+
+```
+-------------------
+FAILED TEST SUMMARY
+-------------------
+test/TestModel.c:21:testInitShouldCallSchedulerAndTemperatureFilterInit: "Function TaskScheduler_Init() called more times than expected."
+
+--------------------
+OVERALL TEST SUMMARY
+--------------------
+TESTED:  1
+PASSED:  0
+FAILED:  1
+IGNORED: 0
+
+---------------------
+BUILD FAILURE SUMMARY
+---------------------
+Unit test failures.
+```
+
+# Configuration
+
+Enable the plugin in your project.yml by adding `stdout_ide_tests_report` to 
+the list of enabled plugins instead of any other `stdout_*_tests_report` 
+plugin.
 
 ``` YAML
 :plugins:

plugins/stdout_ide_tests_report/lib/stdout_ide_tests_report.rb

@@ -5,40 +5,60 @@ class StdoutIdeTestsReport < Plugin
 
   def setup
     @result_list = []
+    @mutex = Mutex.new
+
+    # Set the report template (which happens to be the Ceedling default)
+    @ceedling[:plugin_reportinator].register_test_results_template(
+      DEFAULT_TESTS_RESULTS_REPORT_TEMPLATE
+      )
   end
 
+  # Collect result file paths after each test fixture execution
   def post_test_fixture_execute(arg_hash)
-    return if not (arg_hash[:context] == TEST_SYM)
-
-    @result_list << arg_hash[:result_file]
+    # Thread-safe manipulation since test fixtures can be run in child processes
+    # spawned within multiple test execution threads.
+    @mutex.synchronize do
+      @result_list << arg_hash[:result_file]
+    end
   end
 
-  def post_build
+  # Render a report immediately upon build completion (that invoked tests)
+  def post_build()
+    # Ensure a test task was invoked as part of the build
     return if (not @ceedling[:task_invoker].test_invoked?)
 
-    results = @ceedling[:plugin_reportinator].assemble_test_results(@result_list)
+    results = @ceedling[:plugin_reportinator].assemble_test_results( @result_list )
     hash = {
       :header => '',
       :results => results
     }
 
-    @ceedling[:plugin_reportinator].run_test_results_report(hash) do
+    @ceedling[:plugin_reportinator].run_test_results_report( hash ) do
       message = ''
       message = 'Unit test failures.' if (hash[:results][:counts][:failed] > 0)
       message
     end
   end
 
-  def summary
-    result_list = @ceedling[:file_path_utils].form_pass_results_filelist( PROJECT_TEST_RESULTS_PATH, COLLECTION_ALL_TESTS )
+  # Render a test results report on demand using results from a previous build
+  def summary()
+    # Build up the list of passing results from all tests
+    result_list = @ceedling[:file_path_utils].form_pass_results_filelist(
+      PROJECT_TEST_RESULTS_PATH,
+      COLLECTION_ALL_TESTS
+    )
 
-    # get test results for only those tests in our configuration and of those only tests with results on disk
     hash = {
       :header => '',
-      :results => @ceedling[:plugin_reportinator].assemble_test_results(result_list, {:boom => false})
+      # Collect all existing test results (success or failing) in the filesystem,
+      # limited to our test collection
+      :results => @ceedling[:plugin_reportinator].assemble_test_results(
+        result_list,
+        {:boom => false}
+      )
     }
 
-    @ceedling[:plugin_reportinator].run_test_results_report(hash)
+    @ceedling[:plugin_reportinator].run_test_results_report( hash )
   end
 
 end