HTML reports publishing in Jenkins - Step-by-Step Execution

Process Flow - HTML reports publishing

Start Jenkins Job

↓

Run Tests or Build

↓

Generate HTML Report Files

↓

Archive HTML Reports

↓

Publish HTML Reports Plugin

↓

View Reports in Jenkins UI

↓

End

This flow shows how Jenkins runs a job, generates HTML reports, archives them, publishes via plugin, and then displays them in the Jenkins interface.

Execution Sample

Jenkins

pipeline {
  agent any
  stages {
    stage('Test') {
      steps {
        sh 'run-tests.sh'
      }
    }
  }
  post {
    always {
      publishHTML(target: [
        reportDir: 'reports',
        reportFiles: 'index.html',
        reportName: 'Test Report'
      ])
    }
  }
}

This Jenkins pipeline runs tests, then publishes the HTML report located in 'reports/index.html' using the publishHTML plugin.

Process Table

Step	Action	Files Created	Jenkins Plugin Action	Result
1	Start Jenkins Job	-	-	Job starts running
2	Run tests via shell script	Test output files, including HTML report files in 'reports/'	-	Tests run and generate report files
3	Archive HTML reports	reports/index.html	publishHTML plugin archives report files	Reports archived for publishing
4	Publish HTML reports	reports/index.html	publishHTML plugin processes report	Report becomes visible in Jenkins UI
5	View report in Jenkins UI	-	-	User can open 'Test Report' link to see HTML report
6	Job ends	-	-	Job completes successfully

💡 Job ends after publishing and viewing HTML reports

Status Tracker

Variable	Start	After Step 2	After Step 3	After Step 4	Final
Job Status	Not started	Running	Running	Running	Completed
Report Files	None	reports/index.html created	reports/index.html archived	reports/index.html published	reports/index.html published and viewable
publishHTML Plugin State	Inactive	Inactive	Archiving	Publishing	Published

Key Moments - 3 Insights

Why do we need to specify 'reportDir' and 'reportFiles' in the publishHTML step?

Because Jenkins needs to know where to find the HTML report files to archive and publish them. See execution_table step 3 where 'reports/index.html' is archived based on these settings.

What happens if the HTML report files are not generated before publishing?

The publishHTML plugin will fail to find the files and the report won't be published. This is shown in execution_table step 2 and 3 where report files must exist before archiving.

Can the published HTML report be viewed immediately after the job finishes?

Yes, once the publishHTML plugin processes the files (step 4), the report link appears in Jenkins UI for viewing (step 5).

Visual Quiz - 3 Questions

Look at the execution table, at which step are the HTML report files archived?

A Step 2

B Step 4

C Step 3

D Step 5

💡 Hint

Check the 'Jenkins Plugin Action' column for archiving action in step 3.

According to the variable tracker, what is the state of 'publishHTML Plugin State' after step 4?

A Publishing

B Archiving

C Inactive

D Published

💡 Hint

Look at the 'publishHTML Plugin State' row and the column 'After Step 4'.

If the 'reportDir' is set incorrectly, what will happen according to the execution flow?

A The job will fail to start

B The publishHTML plugin will not find the report files and fail to publish

C Tests will not run

D The report will be published but empty

💡 Hint

Refer to key_moments question about specifying 'reportDir' and 'reportFiles'.

Concept Snapshot

Jenkins HTML Reports Publishing:
- Run tests/build that generate HTML reports
- Use publishHTML plugin in post step
- Specify reportDir and reportFiles
- Plugin archives and publishes reports
- Reports viewable in Jenkins UI after job completes

Full Transcript

This visual execution shows how Jenkins publishes HTML reports. First, the Jenkins job starts and runs tests that generate HTML report files in a directory like 'reports/'. Next, the publishHTML plugin archives these files by specifying the directory and file names. Then, the plugin publishes the reports so they appear as clickable links in the Jenkins UI. Finally, users can view the HTML reports directly from Jenkins after the job finishes. Key points include ensuring the report files exist before publishing and correctly setting the report directory and file names in the plugin configuration.

Practice

1. What is the main purpose of publishing HTML reports in Jenkins?

easy

A. To display test and build results inside Jenkins in a readable format

B. To execute shell commands during the build

C. To send email notifications after a build

D. To create new Jenkins jobs automatically

Solution

1. Step 1: Understand the role of HTML reports in Jenkins

   HTML reports are used to show test and build results in a user-friendly way inside Jenkins.

2. Step 2: Identify the correct purpose

   Among the options, only displaying results inside Jenkins matches the purpose of HTML reports.

3. Final Answer:

   To display test and build results inside Jenkins in a readable format -> Option A

4. Quick Check:

   HTML reports = readable results inside Jenkins [OK]

Hint: HTML reports show results inside Jenkins UI [OK]

Common Mistakes:

• Confusing HTML reports with build execution steps
• Thinking HTML reports send notifications
• Assuming HTML reports create jobs

2. Which of the following is the correct syntax to publish an HTML report in a Jenkins pipeline script?

easy

A. publishHTML { reportDir: 'reports', reportFiles: 'index.html', reportName: 'My Report' }

B. publishHTML(reportDir: 'reports', reportFiles: 'index.html', reportName: 'My Report')

C. publishHTML('reports', 'index.html', 'My Report')

D. publishHTML(target: [allowMissing: false, alwaysLinkToLastBuild: true, keepAll: true, reportDir: 'reports', reportFiles: 'index.html', reportName: 'My Report'])

Solution

1. Step 1: Review the correct Jenkins pipeline syntax for publishHTML

   The publishHTML step requires a target map with keys like allowMissing, alwaysLinkToLastBuild, keepAll, reportDir, reportFiles, and reportName.

2. Step 2: Compare options to syntax

   publishHTML(target: [allowMissing: false, alwaysLinkToLastBuild: true, keepAll: true, reportDir: 'reports', reportFiles: 'index.html', reportName: 'My Report']) correctly uses the target map with all required keys and proper syntax.

3. Final Answer:

   publishHTML(target: [allowMissing: false, alwaysLinkToLastBuild: true, keepAll: true, reportDir: 'reports', reportFiles: 'index.html', reportName: 'My Report']) -> Option D

4. Quick Check:

   publishHTML uses target map syntax [OK]

Hint: Use publishHTML with target map and keys [OK]

Common Mistakes:

• Omitting the target keyword
• Passing parameters as separate arguments
• Using curly braces instead of parentheses

3. Given this Jenkins pipeline snippet:

publishHTML(target: [allowMissing: true, keepAll: false, reportDir: 'test-results', reportFiles: 'summary.html', reportName: 'Test Summary'])

What happens if the 'summary.html' file is missing after the build?

medium

A. The build will fail due to missing report file

B. The build will succeed and no report will be shown

C. Jenkins will create an empty report automatically

D. The build will pause and wait for the file

Solution

1. Step 1: Understand the allowMissing option

   allowMissing: true means Jenkins will not fail the build if the report file is missing.

2. Step 2: Predict behavior when file is missing

   Since allowMissing is true, the build succeeds but no report is shown.

3. Final Answer:

   The build will succeed and no report will be shown -> Option B

4. Quick Check:

   allowMissing true = no failure if missing [OK]

Hint: allowMissing true lets build pass without report [OK]

Common Mistakes:

• Assuming build fails when allowMissing is true
• Thinking Jenkins creates missing files
• Believing build pauses for missing files

4. You configured publishHTML in your Jenkins pipeline but the HTML report does not appear in the build results. Which of these is the most likely cause?

medium

A. The Jenkins server needs a restart

B. The publishHTML step is missing the allowMissing option

C. The reportDir path is incorrect or does not contain the report files

D. The reportName is too long

Solution

1. Step 1: Check common reasons for missing HTML reports

   If the reportDir path is wrong or empty, Jenkins cannot find the report files to display.

2. Step 2: Evaluate other options

   allowMissing missing does not prevent report display if files exist; reportName length and server restart are unrelated.

3. Final Answer:

   The reportDir path is incorrect or does not contain the report files -> Option C

4. Quick Check:

   Wrong reportDir = no report shown [OK]

Hint: Verify reportDir path and files exist [OK]

Common Mistakes:

• Ignoring reportDir correctness
• Thinking allowMissing affects report visibility
• Restarting Jenkins unnecessarily

5. You want Jenkins to keep all HTML reports from every build and always link to the latest report. Which configuration achieves this?

hard

A. publishHTML(target: [keepAll: true, alwaysLinkToLastBuild: true, reportDir: 'output', reportFiles: 'report.html', reportName: 'Build Report'])

B. publishHTML(target: [keepAll: false, alwaysLinkToLastBuild: false, reportDir: 'output', reportFiles: 'report.html', reportName: 'Build Report'])

C. publishHTML(target: [keepAll: true, alwaysLinkToLastBuild: false, reportDir: 'output', reportFiles: 'report.html', reportName: 'Build Report'])

D. publishHTML(target: [keepAll: false, alwaysLinkToLastBuild: true, reportDir: 'output', reportFiles: 'report.html', reportName: 'Build Report'])

Solution

1. Step 1: Understand keepAll and alwaysLinkToLastBuild options

   keepAll: true keeps reports from all builds. alwaysLinkToLastBuild: true creates a link to the latest report.

2. Step 2: Match options to requirement

   publishHTML(target: [keepAll: true, alwaysLinkToLastBuild: true, reportDir: 'output', reportFiles: 'report.html', reportName: 'Build Report']) sets both keepAll and alwaysLinkToLastBuild to true, meeting the requirement.

3. Final Answer:

   publishHTML(target: [keepAll: true, alwaysLinkToLastBuild: true, reportDir: 'output', reportFiles: 'report.html', reportName: 'Build Report']) -> Option A

4. Quick Check:

   keepAll and alwaysLinkToLastBuild true = keep all and link latest [OK]

Hint: Set keepAll and alwaysLinkToLastBuild to true [OK]

Common Mistakes:

• Setting keepAll false loses old reports
• Not linking to last build report
• Confusing option names