Create test report parsing contributor documentation
Problem to solve
We have good documentation about how to use the features in the area of GitLab , but right now there isn't much contributor specific technical documentation for how the code works. I believe that not having this documentation makes code for our features more challenging to contribute to, and more challenging to review for backend maintainers.
This content is designed for making onboarding intofeatures easier for contributors, maintainers, and new GitLab team members.
We should create a minimal amount of feature-specific documentation for JUnit report parsing, including diagrams that can be hosted in the docs.gitlab.com area.
I find diagrams make communicating code architecture with others easier. I have prepared the following diagrams as an exercise for my own understanding of the code. They are very rough, but having these would have been beneficial for me during onboarding.
Graph of the current test report objects:
graph TD; subgraph background pipeline--creates artifact-->junit-report.xml end subgraph User Interaction junit-report.xml--parsed by-->Build Build--gathered by-->Pipeline Pipeline--used by-->PipelinesController PipelinesController--show pipeline-->User end subgraph Test*Entity Build--parses into-->TestReportEntity TestReportEntity--has many-->TestSuiteEntity TestSuiteEntity--has many-->TestCaseEntity end
Sequence diagram of how displaying a test report on a Merge request works:
sequenceDiagram autonumber participant Database participant Pipeline participant FilePersistence participant PipelinesController participant MergeRequestView participant User Note left of Database: Not used by tests rect rgb(191,223,255) Note right of Pipeline: Background Pipeline->>FilePersistence: POST junit.xml from build end rect rgb(100,197,153) Note right of PipelinesController: User-facing User->>MergeRequestView: Load my MR please MergeRequestView->>User: Here is some of it MergeRequestView->>PipelinesController: Request for test_report PipelinesController->>FilePersistence: Give me the junit.xml Note right of PipelinesController: XML report parsing Note right of PipelinesController: Potentially cached PipelinesController->>User: Here are the parsed Test*Entitys end
Who can address the issue
Backend engineers inwould need to take some time to ensure the documentation in this area is high quality and up to our documentation standards. Following a first pass by them, we will need help from a Technical Writer.
The Geo team has some really neat documentation