aft-jira v12.1.1

AFT-Jira

provides Jira result logging as well as test execution filtering for users of aft-core by implementing plugins for the ReportingPlugin and PolicyPlugin plugin base classes.

JiraReportingPlugin

the JiraReportingPlugin extends from ReportingPlugin in aft-core. if enabled, this plugin will, upon receiving a failing test result, check for any existing open defects referencing the Test ID and if found, add a comment that the issue still exists or, if not found, will mark the defect as resolved. it can be enabled by including the following in your aftconfig.json file:

{
    "logLevel": "info",
    "plugins": [
        {"name": "jira-reporting-plugin", "searchDir": "./node_modules"}
    ],
    "JiraConfig": {
        "url": "https://your.jira.instance/",
        "accesskey": "your_jira_access_token",
        "openDefectOnFail": false,
        "closeDefectOnPass": false,
        "projectKey": "ABCD",
        "closedStatusCategoryName": "Done"
    }
}

JiraConfig:

• url - string the url of your Jira instance
• accesskey - string a valid API access token created under your Profile section in Jira
• openDefectOnFail - bool if set to true a new defect will be created if a failed test result is received and not existing defect is found for the Test ID (defaults to false)
• closeDefectOnPass - bool if set to true and a passing test result is received and an open defect is found for the Test ID then the defect will be closed as resolved, fixed (defaults to false)
• projectKey - string the Jira project key (value displayed after projects in the URL when viewing the Jira Project) in which new issues will be created if openDefectOnFail is true
• closedStatusCategoryName - string containing the name visible in the UI for closed Jira issues. this is used to lookup open issues and when transitioning issues to a closed state if closeDefectOnPass is true. (defaults to "Done")

JiraPolicyPlugin

the JiraPolicyPlugin extends from PolicyPlugin interface in aft-core. if enabled this plugin will search Jira for open defects referencing the specified Test IDs from the set of IDs specified in a AftTest and if found this plugin will return a result of false from the shouldRun function. it can be enabled by including the following in your aftconfig.json file:

{
    "logLevel": "info",
    "plugins": [
        {"name": "jira-policy-plugin", "searchDir": "./node_modules"}
    ],
    "JiraConfig": {
        "url": "https://your.jira.instance/",
        "accesskey": "your_jira_access_token",
        "policyEngineEnabled": true
    }
}

Configuration

to open or modify defects in Jira, you will need to have an account with both read and write permissions. These values can be specified in your aftconfig.json as follows:

{
    "JiraConfig": {
        "url": "http://fake.jira.io",
        "accesskey": "your_jira_access_token",
        "policyEngineEnabled": true
    }
}

• url - REQUIRED the full URL to your instance of Jira. (NOTE: this is NOT the API URL, just the base domain name)
• accesskey - string a valid API access token created under your Profile section in Jira
• policyEngineEnabled - bool if set to true then any AftTest with a Test ID will first check that the test should be run via this plugin. any open defects referencing this Test ID will result in a false response (defaults to true)

Usage

you can submit results directly by calling the aft-core.ReportingManager.submitResult(result: TestResult) function or results will automatically be submitted if using the aft-core.AftTest(description, testFunction) with valid testCases specified in the options object.

via aft-core.ReportingManager:

let reporter = new ReportingManager({logName: 'example'});
await reporter.submitResult({
    testId: 'C3190',
    status: TestStatus.Failed,
    resultMessage: 'there was an error when running this test'
});

via aft-core.AftTest (aft-core.AftTest.run()):

/** 
 * new Jira Issue opened for `C3190`, `C2217763`, and `C3131`
 * following execution because `AftTest.status` on exit is `failed`
 * and `verify` call doesn't reference any test IDs
 * #### NOTE:
 * > if open defects exist then a comment is added indicating
 * the issue still occurs instead of creating a duplicate issue
 */
await aftTest('[C3190][C2217763][C3131]', async (t: AftTest) => {
    await t.verify((1 + 1), 3, 'expected to fail because 1+1 != 3');
});