# text-finder-plugin

**Repository Path**: mamh-java/text-finder-plugin

## Basic Information

- **Project Name**: text-finder-plugin
- **Description**: https://github.com/mamh-java/text-finder-plugin
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-05-14
- **Last Updated**: 2025-07-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

= Text Finder Plugin
:toc:
:toc-placement!:
:toc-title:
ifdef::env-github[]
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
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: '<regular expression>', fileSet: '<file set>')])
----

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: '<regular expression>', fileSet: '<file set>', alsoCheckConsoleOutput: true)])
----

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

[source,groovy]
----
findText(textFinders: [textFinder(regexp: '<regular expression>', 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 '<regular expression>'
          fileSet '<file set>'
          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].