Rule basics¶
Checkers¶
Robocop rules are internally grouped into checkers. Each checker can scan for multiple related issues
(like LengthChecker
checks both for minimum and maximum length of a keyword). You can refer to
specific rule reported by checkers by its name or id (for example too-long-keyword or 0501).
- Checkers are categorized into following categories with a corresponding ID:
01: base
02: documentation
03: naming
04: errors
05: lengths
06: tags
07: comments
08: duplications
09: misc
10: spacing
11-50: not yet used: reserved for future internal checkers
51-99: reserved for external checkers
Checkers have three basic types:
VisitorChecker
uses Robot Framework parsing API and Python ast module for traversing Robot code as nodes,ProjectChecker
extendsVisitorChecker
and hasscan_project
method called after visiting all the filesRawFileChecker
simply reads Robot file as normal file and scans every line.
Each rule has a unique 4-digit ID that contains: - a 2-digit category ID (listed above), followed by - a 2-digit rule number.
Rule ID as well as rule name can be used to refer to the rule (e.g. in include/exclude statements, configurations etc.). You can optionally configure rule severity or other parameters.
Listing available rules¶
To get list of available rules (with enabled/disabled status) use -l
/ --list
option:
> robocop --list
Rule - 0201 [W]: missing-doc-keyword: Missing documentation in '' keyword (enabled)
Rule - 0202 [W]: missing-doc-test-case: Missing documentation in '' test case (enabled)
Rule - 0203 [W]: missing-doc-suite: Missing documentation in suite (enabled)
(...)
If some of the rules are disabled from CLI it will be reflected in the output:
> robocop --exclude 02* --list
Rule - 0201 [W]: missing-doc-keyword: Missing documentation in '' keyword (disabled)
Rule - 0202 [W]: missing-doc-test-case: Missing documentation in '' test case (disabled)
Rule - 0203 [W]: missing-doc-suite: Missing documentation in suite (disabled)
Rule - 0301 [W]: not-allowed-char-in-name: Not allowed character '' found in name (enabled)
(...)
Rules list can be filtered out by glob pattern:
> robocop --list tag*
Rule - 0601 [W]: tag-with-space: Tag '' should not contain spaces (enabled)
Rule - 0602 [I]: tag-with-or-and: Tag '' with reserved word OR/AND. Hint: make sure to include this tag using lowercase name to avoid issues (enabled)
Rule - 0603 [W]: tag-with-reserved-word: Tag '' prefixed with reserved word `robot:` (enabled)
Rule - 0606 [I]: tag-already-set-in-test-tags: Tag 'mytag' is already set by Test Tags in suite settings (enabled)
Use -lc \ --list-configurables
argument to list rules together with available configurable parameters. Optional pattern argument is also supported:
robocop --list-configurables empty-lines-between-sections
Rule - 1003 [W]: empty-lines-between-sections: Invalid number of empty lines between sections (/) (enabled)
Available configurables for this rule:
empty_lines = 2
type: int
info: number of empty lines required between sections
To list only enabled or disabled rules:
> robocop -i tag-with* --list ENABLED
Rule - 0601 [W]: tag-with-space: Tag '' should not contain spaces (enabled)
Rule - 0602 [I]: tag-with-or-and: Tag '' with reserved word OR/AND. Hint: make sure to include this tag using lowercase name to avoid issues (enabled)
Rule - 0603 [W]: tag-with-reserved-word: Tag '' prefixed with reserved word `robot:` (enabled)
> robocop -e inconsistent-assignment-in-variables --list-configurables DISABLED
Rule - 0910 [W]: inconsistent-assignment-in-variables: The assignment sign is not consistent inside the variables section. Expected '' but got '' instead (disabled)
assignment_sign_type = autodetect
type: parse_assignment_sign_type
info: possible values: 'autodetect' (default), 'none' (''), 'equal_sign' ('=') or space_and_equal_sign (' =')
Available list filters:
DEFAULT - no pattern specified, print all default rules (enabled and disabled)
ENABLED - print only enabled rules
DISABLED - print only disabled rules
COMMUNITY - print only community rules
DEPRECATED - print only deprecated rules
ALL - print all default and community rules
Rule message¶
Every issue is reported as robocop.rules.Message
object. It can be later printed or used by
post-run reports.
Output message format¶
Output message of rules can be defined with -f
/ --format
argument. Default value:
"{source}:{line}:{col} [{severity}] {rule_id} {desc} ({name})"
Available formats
source
: path to the file where the issue occurredsource_rel
: path to the file where the issue occurred, relative to execution directoryline
: line number where the issue startsend_line
: line number where the issue endscol
: column number where the issue startsend_col
: column number where the issue endsseverity
: severity of the issue, value ofrobocop.rules.RuleSeverity
enumrule_id
: rule id (e.g.0501
)name
: rule name (e.g.line-too-long
)desc
: description of the rule
Rule severity¶
It can be configured with --configure id_or_msg_name:severity:value
where value can be first letter of severity value or whole name, case-insensitive.
For example
-c line-too-long:severity:e
will change line-too-long rule severity to error.
You can filter out all rules below given severity value by using following option:
-t/--threshold <severity value>
To only report rules with severity W and above:
--threshold W
Severity threshold¶
Selected rules can be configured to have different severity depending on the parameter value.
Using line-too-long
as an example - this rule issues a warning when line length exceeds
configured value (default 120
).
It is possible to configure this rule to issue a warning for line length above 120
but an error for line length above 200.
We can use severity_threshold
for this purpose:
robocop -c line-too-long:severity_threshold:warning=120:error=200
It supports all default severity values:
error, e
warning, w
info, i
The issue needs to be raised in order for severity thresholds to be evaluated. That’s why the parameter value needs to
be configured to raise an issue for at least one of our threshold ranges. In previous example, if we want to issue
info message if the line is longer than 80 characters, we need to configure line_length
parameter
(default 120
) to 80 to trigger the rule:
robocop -c line-too-long:line_length:80 -c line-too-long:severity_threshold:info=80:warning=120:error=200
Following rules support severity_threshold
:
Including and excluding rules¶
You can include or exclude particular rules using rule name or id.
Rules are matched in similar way how Robot Framework include
/ exclude
arguments.
Described examples:
robocop --include missing-doc-keyword test.robot
All rules will be ignored except missing-doc-keyword
rule:
robocop --exclude missing-doc-keyword test.robot
Only missing-doc-keyword
rule will be ignored.
Robocop supports glob patterns:
robocop --include *doc* test.robot
All rules will be ignored except those with doc in its name (like missing-doc-keyword
, too-long-doc
etc).
You can provide list of rules in comma-separated format or repeat the argument with value:
robocop --include rule1,rule2,rule3 --exclude rule2 --exclude rule1 test.robot
You can also use short names of options:
robocop -i rule1 -e rule2 test.robot