Support testcase properties (#106)

* Support testset and test properties

* Add JUnit specific details to *_properties docstrings

* Set project version to 1.0.0

* Improve examples

Project.toml

@@ -1,6 +1,6 @@
 name = "TestReports"
 uuid = "dcd651b4-b50a-5b6b-8f22-87e9f253a252"
-version = "0.7.3"
+version = "1.0.0"
 
 [deps]
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"

README.md

@@ -29,16 +29,15 @@ To add to CI:
 $ julia -e 'using Pkg; Pkg.add("TestReports"); using TestReports; TestReports.test("MyPackage")'
 ```
 
-Additionally, properties can be added to your `TestSet`s. To do this, use the `recordproperty`
-function like so:
+Additionally, properties can be associated with your testsets or tests. To do this, use the `record_testset_property` or `record_test_property` functions within a testset:
 
 ```julia
 using Test
 using TestReports
 
 @testset "MyTests" begin
-    recordproperty("ID", 1)
-    @test 1==1
+    record_testset_property("ID", 1)
+    @test 1 == 1
 end
 ```
 

docs/src/index.md

@@ -25,16 +25,15 @@ To add to CI:
 $ julia -e 'using Pkg; Pkg.add("TestReports"); using TestReports; TestReports.test("MyPackage")'
 ```
 
-Additionally, properties can be added to your `TestSet`s. To do this, use the `recordproperty`
-function like so:
+Additionally, properties can be associated with your testsets or tests. To do this, use the `record_testset_property` or `record_test_property` functions within a testset:
 
 ```julia
 using Test
 using TestReports
 
 @testset "MyTests" begin
-    recordproperty("ID", 1)
-    @test 1==1
+    record_testset_property("ID", 1)
+    @test 1 == 1
 end
 ```
 

docs/src/library.md

@@ -12,7 +12,8 @@ Documentation for `TestReports.jl`'s public interface.
 
 ```@docs
 TestReports.test
-recordproperty
+record_testset_property
+record_test_property
 ReportingTestSet
 any_problems
 report

docs/src/manual.md

@@ -77,30 +77,26 @@ julia> TestReports.test(["MyPackage1", "MyPackage2"], logfilename=["1.xml", "2.x
 # File paths are joinpath("path", "1.xml") and joinpath("path", "2.xml")
 ```
 
-## Adding Properties
+## Associating Properties
 
-Properties can be added to a `TestSet` using the exported function `recordproperty`
-within `runtests.jl` and other `include`d scripts:
+Properties can be associated to a testsets and/or tests by using the respective 
+`record_testset_property` and `record_test_property` functions within a testset:
 
 ```julia
 using Test
 using TestReports
 
 @testset "MyTests" begin
-    recordproperty("ID", 1)
-    @test 1==1
+    record_testset_property("ID", 1)
+    @test 1 == 1
 end
 ```
 
-`recordproperty` will have no affect during normal unit testing.
-
-The added properties will be added to the corresponding testsuite in the generated report.
-Multiple properties can be added, and a property added to a parent `TestSet` will be applied
-to all child `TestSet`s.
+The `record_*_property` functions will have no affect during normal unit testing.
 
-Properties with the same name are allowed to be set multiple times within the same
-`TestSet`. If both a parent and a child set the same named property both properties will
-appear in the child when generating the report.
+The associated properties will be added to the corresponding testsuite or testcase in the
+generated report. Multiple properties can be added, and a properties added to a parent
+testset will be applied to all child testsets. Duplicate properties are allowed to be set.
 
 The property name must always be a `String`, but the value can be anything that is serializable
 by `EzXML.jl`. In practice this means that `String`s, `Number`s, `Expr`s and `Symbols` can be used,
@@ -113,19 +109,21 @@ using Test
 using TestReports
 
 @testset "TopLevelTests" begin
-    recordproperty("TestFile" @__FILE__)  # This will be added to all child testsets in report
+    # This will be added to all child testsets in report. May not be appropriate when using
+    # `include`.
+    record_testset_property("TestFile", @__FILE__)
 
     @testset "MiddleLevelTests" begin
-        recordproperty("Testsuite", 100)
-        recordproperty("TestSubject", "Example")
+        record_testset_property("Testsuite", 100)
+        record_test_property("TestSubject", "Example")
 
         @testset "Inner" begin
-            recordproperty("Testsuite", 101)  # Both testsuite 100 and 101 apply to this testset
+            record_testset_property("Testsuite", 101)  # Associate with both testsuite 100 and 101
             @test 1 == 1
         end
 
         @testset "Types" begin
-            recordproperty("Prop1", :Val1)
+            record_test_property("Prop1", :Val1)
             @test 1 == 1
         end
     end

src/TestReports.jl

@@ -32,7 +32,7 @@ else
     using Pkg.Types: SHA1
 end
 
-export ReportingTestSet, any_problems, report, recordproperty
+export ReportingTestSet, any_problems, report, record_test_property, record_testset_property
 
 const TESTREPORTS_VERSION = let # Copied from Documenter.jl
     project = joinpath(dirname(dirname(pathof(TestReports))), "Project.toml")
@@ -50,6 +50,6 @@ include("./testsets.jl")
 include("to_xml.jl")
 include("compat_check.jl")
 include("runner.jl")
-include("recordproperty.jl")
+include("properties.jl")
 
 end # module

src/properties.jl

@@ -0,0 +1,87 @@
+"""
+    record_testset_property(name::AbstractString, value)
+
+Associates a property with the current testset. The `name` and `value` will be turned into a
+`<property>` element within the corresponding `<testsuite>` element within the JUnit XML
+report.
+
+Multiple properties can be added to one testset and child testsets inherit the properties
+defined by their parents. If a child testset records a property which is already set both
+will be present in the resulting report.
+
+The suggested use of this function is to place it inside a testset with unspecified type
+(see Examples). This will ensure that `Pkg.test` is unnaffected, but that the properties
+are added to the report when `TestReports.test` is used. This is because properties are
+only added when the `Testset` type has a `TestReports.testset_properties` method defined, as
+does the `ReportingTestSet` used by `TestReports`. `TestReports.testset_properties` can be
+extended for custom `TestSet`s.
+
+If a child testset has this method defined but its parent doesn't, the property should
+be in the report when `TestReport.test` is used, assuming that the parent testset
+type doesn't do anything to affect the reporting behaviour. However this is not tested
+functionality.
+
+The `value` argument must be serializable by EzXML, which gives quite a lot of freedom.
+
+## Examples
+
+Using the default testset for compatiblity with `Pkg.test` and `TestReports.test`:
+
+```julia
+using TestReports
+
+# Default testset used, record property calls are ignored by `Pkg.test` but will be used
+# when generating JUnit XML.
+@testset "MyTestSet" begin
+    record_testset_property("ID", 42)
+    record_test_property("Bool", true)
+    @test 1 == 1
+    @test 2 == 2
+end
+```
+
+Rendering JUnit reports on the REPL:
+
+```julia
+using Test, TestReports, EzXML
+
+ts = @testset ReportingTestSet "Root" begin  # `<testsuite name="Root">` has property "foo"
+    record_testset_property("foo", 1)
+    record_test_property("bar", 2)
+
+    @testset "Inner" begin  # `<testsuite name="Root/Inner">` has property "foo"
+        @test 1 == 1  # `<testcase>` has the property "bar"
+    end
+
+    @test 2 != 1  # `<testcase>` has the property "bar"
+end;
+
+prettyprint(report(ts))
+```
+
+See also: [`record_test_property`](@ref) and [`testset_properties`](@ref).
+"""
+function record_testset_property(name::AbstractString, value)
+    record_testset_property!(get_testset(), name, value)
+    return value
+end
+
+"""
+    record_test_property(name::AbstractString, value)
+
+Associates a property with the tests contained with the testset. The `name` and `value` will
+be turned into a `<property>` element with the corresponding `<testcase>` element within the
+JUnit XML report.
+
+Multiple test properties can be assigned within a testset and child testsets will inherit
+the test properties defined by their parents. If a child testset records a test property
+with an already used name both properties will be present in the resulting report.
+
+For more details and examples see the documentation for [`record_testset_property`](@ref).
+
+See also: [`record_testset_property`](@ref) and [`test_properties`](@ref).
+"""
+function record_test_property(name::AbstractString, value)
+    record_test_property!(get_testset(), name, value)
+    return value
+end