actions
/
toolkit
mirror of https://github.com/actions/toolkit
1
0
Fork 0
Code

update problem matchers doc for fromPath and default severity (#256)

pull/258/head
eric sciple 2019-12-14 10:11:59 -05:00 committed by GitHub
parent d4975510fe
commit 17acd9c66f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 14 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
docs/problem-matchers.md
View File

@ -1,13 +1,17 @@
# Problem Matchers # Problem Matchers
Problem Matchers are a way to scan the output of actions for a specified regex pattern and surface that information prominently in the UI. Both [GitHub Annotations](https://developer.github.com/v3/checks/runs/#annotations-object-1) and log file decorations are created when a match is detected. Problem Matchers are a way to scan the output of actions for a specified regex pattern and surface that information prominently in the UI. Both [GitHub Annotations](https://developer.github.com/v3/checks/runs/#annotations-object-1) and log file decorations are created when a match is detected.
## Single Line Matchers ## Single Line Matchers
Let's consider the ESLint compact output: Let's consider the ESLint compact output:
``` ```
badFile.js: line 50, col 11, Error - 'myVar' is defined but never used. (no-unused-vars) badFile.js: line 50, col 11, Error - 'myVar' is defined but never used. (no-unused-vars)
``` ```
We can define a problem matcher in json that detects input in that format: We can define a problem matcher in json that detects input in that format:
```json ```json
{ {
"problemMatcher": [ "problemMatcher": [
@ -33,31 +37,34 @@ The following fields are available for problem matchers:
``` ```
{ {
owner: An ID field that can be used to remove or replace the problem matcher. **required** owner: an ID field that can be used to remove or replace the problem matcher. **required**
severity: indicates the default severity, either 'warning' or 'error' case-insensitive. Defaults to 'error'
pattern: [ pattern: [
{ {
regexp: The regex pattern that provides the groups to match against **required** regexp: the regex pattern that provides the groups to match against **required**
file: a group number containing the file name file: a group number containing the file name
fromPath: a group number containing a filepath used to root the file (e.g. a project file)
line: a group number containing the line number line: a group number containing the line number
column: a group number containing the column information column: a group number containing the column information
severity: a group number containing either 'warning' or 'error' case-insensitive. Defaults to `error` severity: a group number containing either 'warning' or 'error' case-insensitive. Defaults to `error`
code: a group number containing the error code code: a group number containing the error code
message: a group number containing the error message. **required** at least one pattern must set the message message: a group number containing the error message. **required** at least one pattern must set the message
loop: loops until a match is not found, only valid on the last pattern of a multipattern matcher loop: whether to loop until a match is not found, only valid on the last pattern of a multipattern matcher
} }
] ]
} }
``` ```
## Multiline Matching ## Multiline Matching
Consider the following output: Consider the following output:
``` ```
test.js test.js
1:0 error Missing "use strict" statement strict 1:0 error Missing "use strict" statement strict
5:10 error 'addOne' is defined but never used no-unused-vars 5:10 error 'addOne' is defined but never used no-unused-vars
✖ 2 problems (2 errors, 0 warnings) ✖ 2 problems (2 errors, 0 warnings)
``` ```
The file name is printed once, yet multiple error lines are printed. The `loop` keyword provides a way to discover multiple errors in outputs. The file name is printed once, yet multiple error lines are printed. The `loop` keyword provides a way to discover multiple errors in outputs.
The eslint-stylish problem matcher defined below catches that output, and creates two annotations from it. The eslint-stylish problem matcher defined below catches that output, and creates two annotations from it.
@ -94,12 +101,15 @@ The first pattern matches the `test.js` line and records the file information. T
The second pattern loops through the remaining lines with `loop: true` until it fails to find a match, and surfaces these lines prominently in the UI. The second pattern loops through the remaining lines with `loop: true` until it fails to find a match, and surfaces these lines prominently in the UI.
## Adding and Removing Problem Matchers ## Adding and Removing Problem Matchers
Problem Matchers are enabled and removed via the toolkit [commands](commands.md#problem-matchers). Problem Matchers are enabled and removed via the toolkit [commands](commands.md#problem-matchers).
## Duplicate Problem Matchers ## Duplicate Problem Matchers
Registering two problem-matchers with the same owner will result in only the problem matcher registered last running. Registering two problem-matchers with the same owner will result in only the problem matcher registered last running.
## Examples ## Examples
Some of the starter actions are already using problem matchers, for example: Some of the starter actions are already using problem matchers, for example:
- [setup-node](https://github.com/actions/setup-node/tree/master/.github) - [setup-node](https://github.com/actions/setup-node/tree/master/.github)
- [setup-python](https://github.com/actions/setup-python/tree/master/.github) - [setup-python](https://github.com/actions/setup-python/tree/master/.github)