Browse Source

Add normalization documentation to README

This adds details about test name normalization to the README, along
with additional documentation on potential output differences and
other caveats involved with this plugin's output.

Change-Id: Id2718ead4a572bd33796706c8d5c04bd671c19c1
Tim Buckley 2 years ago
parent
commit
0477320662
1 changed files with 57 additions and 3 deletions
  1. 57
    3
      README.md

+ 57
- 3
README.md View File

@@ -41,10 +41,64 @@ module.exports = function(config) {
41 41
 
42 42
     subunitReporter: {
43 43
       outputFile: 'karma.subunit',
44
-      tags: [],      // tag strings to append to all tests
45
-      slug: false,   // convert whitespace to '_'
46
-      separator: '.' // separator for suite components + test name
44
+      tags: [],       // tag strings to append to all tests
45
+      slug: false,    // if true, convert whitespace to '_'
46
+      separator: '.', // separator for suite components + test name
47
+      normalize: null // an optional normalization function, see below
47 48
     }
48 49
   });    
49 50
 };
50 51
 ```
52
+
53
+### Normalizing Test Names
54
+
55
+Given that JavaScript's test name formatting conventions are dissimilar to those
56
+in other subunit-supported languages (particularly, Python) it may be desirable
57
+to convert tokens to something that more closely resembles the other languages
58
+in your environment. Additionally, tooling may require that test names be
59
+reasonably well-formed for parsing and categorization purposes.
60
+
61
+In all cases, test name tokens are gathered from karma's `suite` field along
62
+with the test's description. For Jasmine tests, `suite` is an ordered list of
63
+enclosing `describe()` strings for each test. The list of tokens (i.e. suites
64
+plus description) are then passed to some mapping function.
65
+
66
+If not otherwise configured, this mapping function simply returns the list
67
+of tokens unaltered; however, it can also be configured to perform simple
68
+conversions from Jasmine-style test descriptions to simple, dot-separated
69
+Python-ish test names. If configured with `slug: true`, spaces will be collapsed
70
+and converted to `_`, which yields decent results in some cases.
71
+
72
+If more advanced conversion is needed, a custom mapping function can be provided
73
+using the `normalize` parameter, which accepts a list of tokens and returns a
74
+modified list of tokens.
75
+
76
+As a final step, mapped tokens are then joined using the `separator` parameter
77
+(`.` by default).
78
+
79
+## Tags
80
+
81
+The plugin automatically appends certain tags to each test: the browser ID
82
+(`browser-*`) and the spec ID (`spec-*`). If multiple browsers are tested
83
+concurrently these tags can be used to match results across browsers.
84
+
85
+Constant tags to apply to all tests can be also be specified using the `tags`
86
+config option. Each string in the list is unconditionally appended to all tests,
87
+and can be used as a potential compatibility measure (for example, to support
88
+tools that assume a `worker-*` tag should exist).
89
+
90
+## Output Differences
91
+
92
+While in theory this plugin's output should work correctly with all
93
+subunit-compatible tooling, in practice it may violate some assumptions that
94
+can be made safely in other languages.
95
+
96
+For one, tests only run in a single worker thread (and unless configured, no
97
+`worker-#` tag is present). Additionally, within the single worker, tests are
98
+(at least potentially) run asynchronously and may have overlapping execution
99
+timelines.
100
+
101
+Some other minor differences also exist. Currently file attachments aren't
102
+supported, so log output, error messages, and tracebacks won't be included in
103
+the subunit output. There's also no 'setUpClass' or other events that might be
104
+logged in Python tests.

Loading…
Cancel
Save