Issue Tracker

class tcms.issuetracker.models.CredentialTypes(value)

An enumeration.

Models

class tcms.issuetracker.models.IssueTrackerProduct(*args, **kwargs)

Representing a specific issue tracker product

In real world, there are lots of issue tracker products, e.g. Bugzilla, JIRA, GitHub, GitLab, etc. This model represents one of them before adding an issue tracker to model IssueTracker, which could represent a specific deployed instance, for example, the KDE Bugzilla and the GNOME Bugzilla.

exception DoesNotExist
exception MultipleObjectsReturned
class tcms.issuetracker.models.IssueTracker(*args, **kwargs)

Represent a deployed issue tracker instance

exception DoesNotExist
exception MultipleObjectsReturned
property code_name

Return a useful issue tracker name for programmatic purpose

Several characters are replaced. Space in name is replaced with underscore.

Returns:

a formatted name.

Return type:

str

property credential: dict[str, str | None]

Get login credential

The returned credential could contain different login credential data which depends on what credential type is configured for this issue tracker, and how corresponding credential is created.

get_absolute_url()

Get URL linking to this issue tracker

Returns:

the URL.

Return type:

str

classmethod get_by_case(case, enabled=True)

Find out issue trackers for a case

Parameters:
  • case (TestCase) – to get related issue trackers for this test case.

  • enabled (bool) – whether to get enabled issue trackers. If omitted, defaults to True.

Returns:

a queryset of matched issue trackers

Return type:

QuerySet

class tcms.issuetracker.models.ProductIssueTrackerRelationship(*args, **kwargs)

Many-to-many relationship between Product and IssueTracker

Before adding issues to case or case run, an issue tracker must be associated with a product added to Nitrate.

exception DoesNotExist
exception MultipleObjectsReturned
class tcms.issuetracker.models.Issue(*args, **kwargs)

This is the issue which could be added to case or case run

The meaning of issue in issue tracker represents a general concept. In different concrete issue tracker products, it has different name to call, e.g. bug in Bugzilla and issue in JIRA and GitHub.

exception DoesNotExist
exception MultipleObjectsReturned
clean()

Validate issue

static count_by_case_run(case_run_ids: list[int] | None = None)

Subtotal issues and optionally by specified case runs

Parameters:

case_run_ids (list[int]) – list of test case run IDs to just return subtotal for them.

Returns:

a mapping from case run id to the number of issues belong to that case run.

Return type:

dict

class tcms.issuetracker.models.Credential(*args, **kwargs)

Base class providing general functions for credentials

check_secret_file(filename)

Check if secret file is valid for reading credential

Parameters:

filename (str) – the file name of secret file.

Raises:

ValidationError – if cannot read credential from specified secret file.

clean()

General validation for a concrete credential model

Each concrete credential model derived from Credential should call parent’s clean before other validation steps.

class tcms.issuetracker.models.UserPwdCredential(*args, **kwargs)

Username/password credential for logging into issue tracker

exception DoesNotExist
exception MultipleObjectsReturned
clean()

Validate username/password credential

class tcms.issuetracker.models.TokenCredential(*args, **kwargs)

Token based authentication for logging into issue tracker

exception DoesNotExist
exception MultipleObjectsReturned
clean()

Validate token credential

Services

A Service class is created for a specific issue tracker added to model IssueTracker, which is responsible for producing issue and tracker related information, for example, issue report URL.

By default, Nitrate defines three service classes for different possible issue tracker trackers, a general Bugzilla instance, the Red Hat Bugzilla, and JIRA instance. See below for more information. It is free for users to change settings to make it work with user’s environment.

tcms.issuetracker.services.find_service(issue_tracker)

Find out corresponding service class of issue tracker model and return initialized object.

Parameters:

issue_tracker (IssueTracker) – find corresponding service of this issue tracker.

Returns:

instance of service class.

Return type:

a concrete class of IssueTrackerService

Raises:

ValueError – if missing issue tracker’s class_path to find corresponding service.

class tcms.issuetracker.services.IssueTrackerService(tracker_model)

Base issue tracker service

Define and implement base functionalities for an issue tracker service. It is not recommended to initialize object from this class directly. Instead, call factory method find_service() to get a new service object.

A concrete subclass can divide from this base class to implement for specific issue tracker service. Please refer to each method’s docstring to learn what you can customize.

Parameters:

tracker_model (IssueTracker) – the model object of an issue tracker.

add_issue(issue_key, case, case_run=None, summary=None, description=None, add_case_to_issue=None)

Add new issue

An issue could be associated with a single case or with a case and corresponding case run together.

Parameters:
  • issue_key (str) – issue key to add.

  • case (TestCase) – issue key will be added to this case.

  • case_run (TestCaseRun) – optional case run. If passed, issue is associated with this case run as well.

  • summary (str) – optional summary of this issue.

  • description (str) – optional description of this issue.

  • add_case_to_issue (bool) – whether to link case to issue tracker’s external tracker. Defaults to not link test case to the new issue, however if it is required, link_external_tracker() has to be called explicitly.

Returns:

the newly created issue.

Return type:

Issue

Raises:

ValidationError – if fail to validate the new issue.

format_issue_report_content(build_name, case_text)

Format issue report content with a set of information

This method works with IssueTracker.issue_report_templ and provides a set of information to format issue report content. Please refer to the implementation to know what format arguments are provided currently.

Subclasses for specific issue tracker services could override it to format content in different way.

Parameters:
  • build_name (str) – the build name.

  • case_text (TestCaseText or NoneText) – a case’ text object. The report content could be formatted with text provided by this object.

Returns:

formatted issue report content which then can be encoded and be a part of issue report URL argument.

Return type:

str

get_extra_issue_report_url_args(case_run)

Get extra issue report URL arguments

This is where to construct and return extra issue report URL arguments which are not able to be defined in IssueTracker.issue_report_params. For example, some arguments are already defined in that field, and Nitrate also needs to support other custom fields for a specific issue tracker service, e.g., cf_field_a, and the logic to construct their values would be more complicated than just giving a simple value directly, developer could divide from class IssueTrackerService and override this method to provide those custom fields.

Note that, any argument listed in IssueTracker.issue_report_params will overwrite the one in extras.

Parameters:

case_run (TestCaseRun) – a test case run from which to get required information for supported issue report URL arguments.

Returns:

a mapping whose key is argument name and value is the argument value. It is not necessary to consider URL encode here.

Return type:

dict[str, str]

get_stock_issue_report_args(case_run)

Get service supported issue report arguments and their values in key/value pair.

Define and return what issue report arguments and their default value current issue tracker service supports. This is useful for someone, might be a Nitrate administrator who has proper permissions to manage issue tracker, to select part or all arguments to define the lines in IssueTracker.issue_report_params.

Subclass could override this method to customize the for a specific issue tracker.

Parameters:

case_run (TestCaseRun) – a test case run whose relative objects through ORM relationship could be used to customize arguments’ value.

Returns:

a mapping containing stock issue report URL format arguments.

Return type:

dict[str, str]

Add case link to an issue’s external tracker

Some issue tracker product, like Bugzilla, allows to define external trackers in order to relative external resources for an issue. Instead of adding a case ID into issue, Nitrate allows to add case ID to an issue in that kind of external trackers.

However, what does the issue’s external tracker look like? It depends. Some issue tracker might be different without similar external tracker like Bugzilla supports. In such case, developer has to handle the concrete case for specific case.

Subclass for specific issue tracker is responsible for implement this method.

Parameters:

issue (Issue) – an issue whose relative case ID will be added to this issue’s external tracker.

make_issue_report_url(case_run)

Make issue report URL

Issue report URL is used to file an issue in a specific issue tracker. Any concrete issue tracker services derived from IssueTrackerService could override this method or relative private methods to customize the final URL.

Parameters:

case_run (TestCaseRun) – a case run for which to file an issue. The needed data could be retrieved through relationship path from this case run.

Returns:

a complete URL to file an issue.

Return type:

str

make_issues_display_url(issue_keys)

Make URL linking to issue tracker to display issues

This requires issue tracker’s issues_display_url_fmt is set, which accepts a string format argument issue_keys.

By default, issue keys are concatenated and separated by comma. This should work for most of kind of issue tracker product, for example, Bugzilla and JIRA. However, if it does not work for some other issue tracker, developer has to subclass IssueTrackerService and override this method to construct the display URL.

Parameters:

issue_keys (list[str]) – list of issue keys.

Returns:

the display URL which could be opened in Web browser to display specified issues.

Return type:

str

property tracker_model: IssueTracker

Property to access issue tracker model

class tcms.issuetracker.services.Bugzilla(tracker_model)

Represent general Bugzilla issue tracker

get_extra_issue_report_url_args(case_run)

Get extra URL arguments for reporting issue in Bugzilla

get_stock_issue_report_args(case_run)

Get issue report arguments Bugzilla supports

For filing a bug in a Bugzilla service, following arguments are supported:

  • short_desc: content of bug summary.

  • version: product version.

  • component: selected component.

  • product: selected product name.

For the details of parameters and return value, please refer to IssueTrackerService.get_stock_issue_report_args().

class tcms.issuetracker.services.RHBugzilla(tracker_model)

Representing Red Hat Bugzilla

get_extra_issue_report_url_args(case_run)

Add URL arguments which are specific to Red Hat Bugzilla

Link case to issue’s external tracker in remote Bugzilla service

class tcms.issuetracker.services.JIRA(tracker_model)

Represent general JIRA issue tracker