Text Finder Plugin

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

Pipeline jobs

The basic Pipeline syntax is as follows:

findText(textFinders: [textFinder(regexp: '<regular expression>', fileSet: '<file set>')])

The regular expression uses the syntax supported by the Java 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 FileSet type for details.

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

findText(textFinders: [textFinder(regexp: '<regular expression>', fileSet: '<file set>', alsoCheckConsoleOutput: true)])

Note that if you just want to check the console log, you can omit the file set:

findText(textFinders: [textFinder(regexp: '<regular expression>', alsoCheckConsoleOutput: true)])

To downgrade the build result, use the following syntax:

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

If a match is found, the build result will be set to this value. Note that 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:

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

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

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

Freestyle jobs

This plugin provides Job DSL support for Freestyle jobs using the Dynamic DSL. For example:

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:

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 Jenkins issue tracker. Use the text-finder-plugin component in the JENKINS project.

Contributing

Refer to our contribution guidelines.