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:
- 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.
- 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
- 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’sclean
before other validation steps.
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:
- 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
orNoneText
) – 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:
- 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 classIssueTrackerService
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.
- 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.
- link_external_tracker(issue)
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:
- 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 argumentissue_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.
- 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
- class tcms.issuetracker.services.JIRA(tracker_model)
Represent general JIRA issue tracker