text-finder-plugin

= Text Finder Plugin :toc: :toc-placement!: :toc-title: ifdef::env-github[] :tip-caption: 💡 :note-caption: ℹ️ :important-caption: ❗ :caution-caption: 🔥 :warning-caption: ⚠️ endif::[]

https://ci.jenkins.io/job/Plugins/job/text-finder-plugin/job/master/[image:https://ci.jenkins.io/job/Plugins/job/text-finder-plugin/job/master/badge/icon[Build Status]] https://github.com/jenkinsci/text-finder-plugin/graphs/contributors[image:https://img.shields.io/github/contributors/jenkinsci/text-finder-plugin.svg[Contributors]] https://plugins.jenkins.io/text-finder[image:https://img.shields.io/jenkins/plugin/v/text-finder.svg[Jenkins Plugin]] https://github.com/jenkinsci/text-finder-plugin/releases/latest[image:https://img.shields.io/github/release/jenkinsci/text-finder-plugin.svg?label=changelog[GitHub release]] https://plugins.jenkins.io/text-finder[image:https://img.shields.io/jenkins/plugin/i/text-finder.svg?color=blue[Jenkins Plugin Installs]]

toc::[]

== Introduction

This plugin lets you search for some text using regular expressions in a set of files or the console log. Based on the outcome, you can downgrade the build result to UNSTABLE, FAILURE, NOT_BUILT, or ABORTED.

For example, you can search for the string failure in a set of log files. If a match is found, you can downgrade the build result from SUCCESS to FAILURE. This is handy when you have some tools in your build chain that do not properly set the exit code.

== Getting started

=== https://jenkins.io/doc/book/pipeline/[Pipeline] jobs

The basic Pipeline syntax is as follows:

[source,groovy]

findText(textFinders: [textFinder(regexp: '', fileSet: '')])

The regular expression uses the syntax supported by the Java https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html[`Pattern`] class. The file set specifies the path to the files to search, relative to the workspace root. This can use wildcards, like logs/**/*/*.txt. See the documentation for the @includes attribute of the Ant https://ant.apache.org/manual/Types/fileset.html[`FileSet`] type for details.

To also check the console log, use the following syntax:

[source,groovy]

findText(textFinders: [textFinder(regexp: '', fileSet: '', alsoCheckConsoleOutput: true)])

If you just want to check the console log, you can omit the file set:

[source,groovy]

findText(textFinders: [textFinder(regexp: '', alsoCheckConsoleOutput: true)])

To downgrade the build result, use the following syntax:

[source,groovy]

findText(textFinders: [textFinder([...], buildResult: 'UNSTABLE')])

If a match is found, the build result will be set to this value.

NOTE: The build result can only get worse, so you cannot change the result to SUCCESS if the current result is UNSTABLE or worse.

Whether or not a build is downgraded depends on its change condition. The default change condition is MATCH_FOUND, which downgrades the build result if a match is found. To downgrade the build result if a match is not found, set the change condition to MATCH_NOT_FOUND:

[source,groovy]

findText(textFinders: [textFinder([...], changeCondition: 'MATCH_NOT_FOUND', buildResult: 'UNSTABLE')])

To search for multiple regular expressions, use the following syntax:

[source,groovy]

findText(textFinders: [
textFinder(regexp: '<regular expression 1>', [...]),
textFinder(regexp: '<regular expression 2>', [...]),
textFinder(regexp: '<regular expression 3>', [...])
])

=== Freestyle jobs

This plugin provides https://plugins.jenkins.io/job-dsl/[Job DSL] support for Freestyle jobs using https://github.com/jenkinsci/job-dsl-plugin/wiki/Dynamic-DSL[the Dynamic DSL]. For example:

[source,groovy]

job('example') {
publishers {
findText {
textFinders {
textFinder {
regexp ''
fileSet ''
changeCondition '<MATCH_FOUND or MATCH_NOT_FOUND>'
alsoCheckConsoleOutput true
buildResult 'UNSTABLE'
}
}
}
}
}

To search for multiple regular expressions, use the following syntax:

[source,groovy]

job('example') {
publishers {
findText {
textFinders {
textFinder {
regexp '<regular expression 1>'
[...]
}
textFinder {
regexp '<regular expression 2>'
[...]
}
textFinder {
regexp '<regular expression 3>'
[...]
}
}
}
}
}

== Issues

Report issues and enhancements in the https://issues.jenkins.io/[Jenkins issue tracker]. Use the text-finder-plugin component in the JENKINS project.

== Contributing

Refer to our https://github.com/jenkinsci/.github/blob/master/CONTRIBUTING.md[contribution guidelines].