Linting

UTAM provides the ability to statically analyze JSON files to prevent common bad practices, such as duplication of page objects or violations of the encapsulation pattern.

We encourage you not to disable any linting rules and to make sure that your page objects comply with recommended best practices.

This documentation is relevant for UTAM Java versions after 2.0.4 and UTAM JavaScript versions after 2.1.2. Prior to these versions UTAM also produced console output from the linter, this is no longer the case.

Linting is run during the page object compilation process. All warnings and errors are printed into a Static Analysis Results Interchange Format (SARIF) report generated after compilation. SARIF is a common format to store linting results. UTAM creates utam-lint.sarif in the SARIF JSON format, which looks like this:

The SARIF file is in JSON format. To view (pretty print) SARIF files in a terminal or in your IDE, use available tools, such as sarif-fmt or Sarif VSCode extension.

If at least one linting violation of level error occurs and the throwError configuration parameter is set to true (see the next section), the page object compiler throws an exception.

A file in SARIF format can be integrated with development tools such as GitHub to show linting rule violations: SARIF GitHub

GitHub documentation is here.

All linting rules and violation types (error or warning) are configurable as lint properties in the compiler configuration. If a compiler configuration doesn't have a lint section, default values are applied.

  • lintingOutputFile String, default is "utam-lint.sarif". This parameter sets the path for a SARIF log file generated by the UTAM linter. The path is relative to the root of the project.

  • disable Boolean, default is false. If set to true, linting rules are not applied after the compilation.

  • throwError Boolean, default is false. If set to true, the linting process throws an error after reporting errors to the log.

  • <name of the rule> is one of the rules listed in the next section.

    • violation The violation type. Possible values are: warning, error, or disabled (disable the rule). Starting from compiler versions 2.0.3 (utam-js) and 2.0.2 (utam-java), the default is always warning.
    • exclude Is an array of strings that are excluded from the rule. Each string value is a page object URI.
    • additionalConfiguration Is an object containing additional configuration data for the rule, if any applies. See the rule description for information about what additional configuration the rule supports.

Rules with error codes that start with 2 are applicable for one page object only. Rules with error codes that start with 3 are relevant for multiple page objects only, such as detecting duplicates from the earlier example.
  • Rule: page object elements in the same scope (with the same immediate parent) can't have duplicate selectors except if one of the elements is a list.
  • How to fix: remove one or more duplicate elements.
  • Error code: 2001
  • Default violation type: warning

Example:

  • Rule: it's a good practice to provide a description at the page object root level to explain the intended usage of the page object.
  • How to fix: add a page object description.
  • Error code: 2002
  • Default violation type: warning

Example:

  • Rule: The page object description should include an author.
  • How to fix: add an author property to the description.
  • Error code: 2005
  • Default violation type: warning

Example:

  • Rule: it's a good practice to provide a description at the method level that explains the use cases. This rule isn't applied to elements; it's for compose methods only.
  • How to fix: add a method description.
  • Error code: 2003
  • Default violation type: warning

Example:

  • Rule: two page objects with the same root selector usually means a violation of the encapsulation rule (1:1 mapping between a component and a page object).
  • How to fix: remove the duplicate page object. Make sure that you keep all functionality.
  • Error code: 3001
  • Default violation type: warning

Example:

  • Rule: if an element has the same selector as the root selector of a different page object, it should have the same type as the given page object.
  • How to fix: add the proper type, which is the type of the page object with the root selector.
  • Error code: 3002
  • Default violation type: warning

Example:

  • Rule: if an element in one page object has a custom type and a custom selector (with "-"), any element with the same selector in a different page object should have the same custom type.
  • How to fix: change the element type to custom.
  • Error code: 3003
  • Default violation type: warning

Example:

  • Rule: if a page object does not contain a metadata property, or the object value of the metadata property does not contain the specified values.
  • How to fix: add a metadata object containing mandatory fields (if any) to the page object.
  • Error code: 2006
  • Default violation type: disabled
  • Note: additionalConfiguration should contain a requiredProperties array, which will contain objects defining the required properties in the metadata.

Example: