Quality Gates

Quality Gates in Squore allow you to define pass/fail criteria that can be evaluated for every version of your project. They are defined in your model by including content in the quality gates Bundle.xml file. In this chapter, you will learn the syntax of the quality gates bundle and how to configure gates and criteria.

A quality gates bundle looks similar to this:

<?xml version="1.0" encoding="UTF-8"?>
<bundle>
	<gate id="MY_QUALITY_GATE" optional="true">
		<title>
			<label lang="en">My Quality Gate</label>
		</title>
		<criteria>
			<criterion>
				<title>
					<label lang="en">Lines of code must be greater than 100</label>
				</title>
				<value>
					<measure id="LC" />
				</value>
				<condition>
					<test operator="gt" value="100" />
				</condition>
			</criterion>
		</criteria>
	</gate>
</bundle>

Quality gates are evaluated during the analysis and determine whether the project meets the defined quality standards. Each gate contains one or more criteria, and the gate passes only if all its criteria pass.

In addition to being defined in a quality gates bundle, quality gates can be managed through the web interface.

Figure 1. The Quality Gates page.

The "CLI parameter" can be used to select quality gates, but not to manage them.

You only need to learn the quality gates bundle syntax if you want to define default gates in your model configuration.

The XML Schema for the quality gates bundle is described in qualitygates.xsd.

Definition Type

The root bundle element contains one or more gate elements:

<?xml version="1.0" encoding="UTF-8"?>
<bundle>
	<gate id="GATE_1" optional="true">...</gate>
	<gate id="GATE_2">...</gate>
    ...
</bundle>

Each gate element defines a quality gate with the following attributes and sub-elements:

id (mandatory) is the unique identifier of the quality gate. Must match the pattern [A-Z_][A-Z0-9_]+.
optional (optional, default: true) indicates whether the quality gate can be disabled at build time. If false, the gate is always evaluated.
title (optional) provides multi-language labels for the quality gate. If no title is defined, the gate id is used as the display name.
criteria (optional) contains the list of criteria to evaluate.

Title

The title element allows you to define labels in multiple languages:

<title>
	<label lang="en">My Quality Gate</label>
	<label lang="fr">Ma Quality Gate</label>
</title>

Each label element has:

lang (mandatory) the language code (e.g., en, fr).

Displayed properties such as Title and Language are defined in the .properties file.

Criteria

The criteria element contains one or more criterion elements.

criterion (optional) defines a single condition to check during the build, contains the following sub-elements:
- title (mandatory) provides multi-language labels for the criterion. Uses the same format as the gate title.
- description (optional) provides a multi-language description. Uses the same format as title.
- scope (optional) defines which artifacts are used to compute the value. Required for count and findings-count value types.
value (mandatory) defines what is being measured.
condition (mandatory) defines the pass/fail condition.

<?xml version="1.0" encoding="UTF-8"?>
<bundle>
    <gate id="PR_BASED" optional="true">
        <title>
            <label lang="en">PR Based Gate</label>
        </title>

        <criteria>
            <criterion>
                <title>
                    <label lang="en">No findings on new artifacts</label>
                </title>
                <scope>
                    <artifacts>
                        <path scope="DESCENDANTS" artifact-types="CODE;TEST_CASE;TEST_EXECUTION;REQ">
                            <where>
                                <computation test="IS_NEW_ARTEFACT()" />
                            </where>
                        </path>
                    </artifacts>
                </scope>
                <value>
                    <findings-count />
                </value>
                <condition>
                    <test operator="eq" value="0" />
                </condition>
            </criterion>

            <criterion>
                <title>
                    <label lang="en">No findings on modified code artifacts</label>
                </title>
                <scope>
                    <artifacts>
                        <path scope="DESCENDANTS" artifact-types="CODE">
                            <where>
                                <computation test="NOT(IS_NEW_ARTEFACT()) AND SI&lt;1" />
                            </where>
                        </path>
                    </artifacts>
                </scope>
                <value>
                    <findings-count />
                </value>
                <condition>
                    <test operator="eq" value="0" />
                </condition>
            </criterion>

        </criteria>
    </gate>
</bundle>

Value Types

value (mandatory) must contain exactly one of the following child elements:
- measure (optional) retrieves the value of a measure at the project (application) level.
  <value> <measure id="LC" /> </value>
- count(optional) counts the number of artifacts matching the defined scope. The scope element is required when using count. It is required for count and findings-count value types.
  <value> <count /> </value>
- finding-count(optional) counts findings (rule violations) matching optional filter conditions. The scope element is required. Accepts an optional where sub-element to filter findings:
  - where contains one or more finding-condition elements.
    
    finding-condition has a mandatory test attribute containing a filter expression (e.g., MEASUREID=R_COMPOUND).
    
    <value> <findings-count> <where> <finding-condition test="MEASUREID=R_COMPOUND" /> </where> </findings-count> </value>

Scope

scope (optional) defines which artifacts are used to compute the value. Required for count and findings-count value types. Contains the following child element:
- artifact(mandatory) contains a single path element defining the artifact selection.
  - path(mandatory) contains a single path element defining the artifact selection.
    
    scope (optional) defines the tree traversal scope. Valid values are:
    
    CHILDREN — only direct children of the root artifact.
    
    DESCENDANTS — all descendants of the root artifact.
    
    artifact-types (optional) a semicolon-separated list of artifact type IDs to include (e.g., JAVA_FILE;CPP_FILE).
    
    excluding-types (optional) a semicolon-separated list of artifact type IDs to exclude.
    
    <scope> <artifacts> <path scope="DESCENDANTS" artifact-types="JAVA_FILE" excluding-types="JAVA_TEST" /> </artifacts> </scope>

where (in path)

path can contain an optional where element with computation filters:
- computation has a mandatory test attribute containing a computation expression to filter artifacts.
  <path scope="DESCENDANTS" artifact-types="JAVA_FILE"> <where> <computation test="LC>100" /> </where> </path>

Condition

condition (mandatory) defines the pass/fail condition for the evaluated value.
- test (mandatory) defines the pass/fail condition. Contains the `test`elements which accepts the following attribute
  - operator (optional, default: eq) the comparison operator. Valid values are:
    
    eq Equal to
    
    ne Not equal to
    
    gt Greater than
    
    lt Less than
    
    ge Greater than or equal to
    
    le Less than or equal to
  - value (mandatory) the numeric threshold value to compare against.
    
    <condition> <test operator="gt" value="100" /> </condition>

The criterion passes if the evaluated value satisfies the condition: evaluated_value <operator> threshold_value.

Examples

Simple measure check

A gate that checks if the number of lines of code is greater than 100:

<?xml version="1.0" encoding="UTF-8"?>
<bundle>
	<gate id="CODE_SIZE_CHECK" optional="true">
		<title>
			<label lang="en">Code Size Check</label>
		</title>
		<criteria>
			<criterion>
				<title>
					<label lang="en">Lines of code must exceed 100</label>
				</title>
				<value>
					<measure id="LC" />
				</value>
				<condition>
					<test operator="gt" value="100" />
				</condition>
			</criterion>
		</criteria>
	</gate>
</bundle>

Artifact count with scope

A gate that checks whether exactly one file has more than 100 lines of code:

<?xml version="1.0" encoding="UTF-8"?>
<bundle>
	<gate id="ARTIFACT_COUNT_CHECK">
		<criteria>
			<criterion>
				<title>
					<label lang="en">Only one large file allowed</label>
				</title>
				<scope>
					<artifacts>
						<path scope="DESCENDANTS" artifact-types="JAVA_FILE">
							<where>
								<computation test="LC&gt;100" />
							</where>
						</path>
					</artifacts>
				</scope>
				<value>
					<count />
				</value>
				<condition>
					<test operator="eq" value="1" />
				</condition>
			</criterion>
		</criteria>
	</gate>
</bundle>

Findings count with filter

A gate that ensures no findings of a specific rule exist:

<?xml version="1.0" encoding="UTF-8"?>
<bundle>
	<gate id="NO_VIOLATIONS">
		<title>
			<label lang="en">No Critical Violations</label>
			<label lang="fr">Aucune violation critique</label>
		</title>
		<criteria>
			<criterion>
				<title>
					<label lang="en">No compound rule violations</label>
					<label lang="fr">Aucune violation de règle composée</label>
				</title>
				<description>
					<label lang="en">Checks that there are no compound rule violations in the code.</label>
				</description>
				<scope>
					<artifacts>
						<path scope="DESCENDANTS" artifact-types="CODE" excluding-types="JAVA_FILE" />
					</artifacts>
				</scope>
				<value>
					<findings-count>
						<where>
							<finding-condition test="MEASUREID=R_COMPOUND" />
						</where>
					</findings-count>
				</value>
				<condition>
					<test operator="eq" value="0" />
				</condition>
			</criterion>
		</criteria>
	</gate>
</bundle>