Merge pull request #10556 from circleci/test-216/bulk-file-mapper

TEST-216 Update file-mapper docs

Author: gordonsyme

docs/guides/modules/test/pages/testsuite-configuration-reference.adoc

@@ -135,20 +135,70 @@ run: go tool gotestsum --junitfile="<< outputs.junit >>" -- -race -count=1 << te
 [#file-mapper]
 == *`file-mapper`*
 
-When test atoms are not files, Smarter Testing cannot determine which test files belong to which test atom. The `file-mapper` creates a mapping of test atoms to related test files.
+When test atoms are not files, Smarter Testing cannot determine which test files belong to which test atom. The `file-mapper` command creates a mapping of test atoms to related test files.
 
 * During analysis, Smarter Testing can associate test files with their test atoms in impact data.
 * During selection, Smarter Testing can determine which test atom to run when a test file is modified.
 
-The test atom to map can be specified in one of two ways:
+File mapper maps all test atoms to test files in a single pass.
+
+The test atoms to map can be specified in one of two ways:
 
 * Use the template variable `<< test.atoms >>` in the `file-mapper` command.
-* If the template variable is not found in the `file-mapper` command, the test atom will be passed on stdin.
+* If the template variable is not found in the `file-mapper` command, the test atoms will be passed on stdin separated by newlines.
+
+File mapper supports two different output formats:
+
+* *Go list JSON format* `<< outputs.go-list-json >>`.
+* *CircleCI list format* `<< outputs.circleci-list >>`.
+
+=== *Go list JSON format*
+
+Go list JSON format is the format produced by `go list -json="Dir,ImportPath,TestGoFiles,XTestGoFiles" ./\...`.
+
+It consists of one or more JSON documents separated by newlines. Note that each record is a separate JSON document.
+
+.Example showing Go list JSON format
+[source,json]
+----
+{
+	"Dir": "/home/user/dev/module-name/internal/foo",
+	"ImportPath": "github.com/org/module-name/internal/foo",
+	"TestGoFiles": [
+		"foo_test.go"
+	]
+}
+{
+	"Dir": "/home/user/dev/module-name/internal/bar",
+	"ImportPath": "github.com/org/module-name/internal/bar",
+	"XTestGoFiles": [
+		"bar_test.go",
+		"baz_test.go",
+		"shared_test.go"
+	]
+}
+----
+
+=== *CircleCI list format*
+
+CircleCI list format is a plain text, record oriented format. It consists of one or more records separated by newlines.
+
+Each record begins with a line starting with `TA:`, followed by the test atom name.
 
-File mapper can run in two modes:
+Each subsequent line lists a file that contains code for the test atom.
 
-* *One test atom at a time.* This mode expects a list of files back for a passed in `<< test.atom >>`.
-* *All test atoms in a single pass.* This mode supports `<< outputs.go-list-json >>` to map all go test files to go packages.
+Each line must be fewer than 32,768 characters long.
+
+.Example showing CircleCI list format
+[source]
+----
+TA:TestFooClass
+src/foo_test.py
+src/bar_test.py
+
+TA:TestQuzClass
+src/quz_test.py
+----
 
 [.table-scroll]
 --
@@ -163,15 +213,22 @@ File mapper can run in two modes:
 |===
 --
 
-*Example:*
-
+.Example of file-mapper using `<< outputs.go-list-json >>`
 [%linenums,yaml]
 ----
 ---
 name: go tests
 file-mapper: go list -json="Dir,ImportPath,TestGoFiles,XTestGoFiles" ./... > << outputs.go-list-json >>
 ----
 
+.Example of file-mapper using `<< outputs.circleci-list >>`
+[%linenums,yaml]
+----
+---
+name: python tests
+file-mapper: for _atom in << test.atoms >>; do echo "TA:${_atom}"; echo "${_atom}" | sed -E 's/::.*$//'; done > << outputs.circleci-list >>
+----
+
 '''
 
 [#analysis]

styles/config/vocabularies/Docs/accept.txt

@@ -205,6 +205,7 @@ Jenkins
 JFrog
 Jira
 jq\b
+JSON
 \bJUnit\b
 junit
 JRuby