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 extends VisitorChecker and has scan_project method called after visiting all the files

  • RawFileChecker 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 'robocop' keyword (enabled)
Rule - 0202 [W]: missing-doc-test-case: Missing documentation in 'robocop' 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 'robocop' keyword (disabled)
Rule - 0202 [W]: missing-doc-test-case: Missing documentation in 'robocop' 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 occurred

  • source_rel: path to the file where the issue occurred, relative to execution directory

  • line: line number where the issue starts

  • end_line: line number where the issue ends

  • col: column number where the issue starts

  • end_col: column number where the issue ends

  • severity: severity of the issue, value of robocop.rules.RuleSeverity enum

  • rule_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