Update gitlab-ci.yml

3 files changed, 63 insertions, 13 deletions

diff --git a/doc/ci/examples/README.md b/doc/ci/examples/README.md
index 811f4d1f07a..2fc107e2bf5 100644
--- a/doc/ci/examples/README.md
+++ b/doc/ci/examples/README.md
@@ -43,6 +43,10 @@ There's also a collection of repositories with [example projects](https://gitlab
 - [Using `dpl` as deployment tool](deployment/README.md)
 - [The `.gitlab-ci.yml` file for GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab-ci.yml)
 
+## Test Reports
+
+[Collect test reports in Verify stage](test_reports.md).
+
 ## Code Quality analysis
 
 **(Starter)** [Analyze your project's Code Quality](code_quality.md).
diff --git a/doc/ci/examples/test_reports.md b/doc/ci/examples/test_reports.md
index e151d4aaf4e..0e41f8d59e4 100644
--- a/doc/ci/examples/test_reports.md
+++ b/doc/ci/examples/test_reports.md
@@ -1 +1,43 @@
-# TODO:
+# Collect Test Reports in Verify stage
+
+As of GitLab 11.2, you can collect test reports to concreate your [Verify](link) step in DevOps toolchain.
+
+All you need is to specify `artifacts:reports` keyword in gitlab-ci.yml, and specify the most convenient format from [the available formats](link).
+
+For example, we have three jobs in `test` stage and we want to collect JUnit test reports from each job.
+
+```yaml
+rspec 0 3:
+  stage: test
+  script:
+  - bundle install
+  - rspec spec/lib/ --format RspecJunitFormatter --out rspec.xml
+  artifacts:
+    reports:
+      junit: rspec.xml
+
+rspec 1 3:
+  stage: test
+  script:
+  - bundle install
+  - rspec spec/models/ --format RspecJunitFormatter --out rspec.xml
+  artifacts:
+    reports:
+      junit: rspec.xml
+
+rspec 2 3:
+  stage: test
+  script:
+  - bundle install
+  - rspec spec/features/ --format RspecJunitFormatter --out rspec.xml
+  artifacts:
+    reports:
+      junit: rspec.xml
+```
+
+You need to tweak `script` to create a JUnit format report, int this example, we use [`RSpec JUnit Formatter`](https://github.com/sj26/rspec_junit_formatter)
+You can find other tools for other programming languages. Since [JUnit specification](junit-specification) is pretty simple, it would be possible to create your custom formatter.
+
+After each job has been executed by [GitLab-runner](link), `rspec.xml` are stored in GitLab, and surface in [Merge request widget](link).
+
+[junit-specification]: https://www.ibm.com/support/knowledgecenter/en/SSQ2R2_14.1.0/com.ibm.rsar.analysis.codereview.cobol.doc/topics/cac_useresults_junit.html
diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index 10d6d16d7f7..cd9f352cccc 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -1097,29 +1097,33 @@ job:
 > Introduced in GitLab 11.2
 > This feature requires GitLab Runner version 11.2 or above
 
-`reports` keyword allows you to show 
+`reports` keyword is for collecting test reports from jobs and integrate it with GitLab flow,
+such as merge request or Pipeline views.
 
-save report-type artifacts (e.g. JUnit XML),
-internally parse & analyze the results, and surface the results.
+Currently, the following type of reports are supported in GitLab
+
+- [JUnit](link)
+
+### `artifacts:reports:junit`
+
+`junit` is to collect JUnit XML as an artifact. You can see the format specification [here](link).
+Typically, JUnit XML is not only supported in Java, but also there are bunch of thrid party tool to generate JUnit XML from even Ruby, Python or Javascript.
+
+Here is an example of collecting JUnit XML from "rspec" job.
 
 ```yaml
-rspec 0 3:
+rspec:
   stage: test
   script:
+  - bundle install
   - rspec --format RspecJunitFormatter --out rspec.xml
   artifacts:
     reports:
       junit: rspec.xml
 ```
 
-### `artifacts:reports:junit`
-
-`junit` is to specify paths of JUnit style XML test reports 
-
-```
-
-```
-
+The collected JUnit report will be persisted in GitLab as well as a general artiafcts (i.e. `artifacts:paths`) will.
+Without any further configuration, GitLab will automatically parse those reports and surface on UI, such as merge requests.
 
 ## `dependencies`