Issue Trackers: package `fuzzinator.tracker`¶

class fuzzinator.tracker.BugzillaTracker(*args, **kwargs)¶

Bugzilla issue tracker.

Mandatory parameters of the issue tracker:

url: URL of the Bugzilla installation.

product: the name of the SUT in the Bugzilla.

Optional parameter of the issue tracker:

api_key: an API key for authenticating.

Example configuration snippet:

[sut.foo]
tracker=fuzzinator.tracker.BugzillaTracker

[sut.foo.tracker]
url=https://bugzilla.example.org
product=foo
api_key=1234567890123456789012345678901234567890

class fuzzinator.tracker.GithubTracker(*args, **kwargs)¶

GitHub issue tracker.

Mandatory parameter of the issue tracker:

repository: repository name in user/repo format.

Optional parameter of the issue tracker:

token: a personal access token for authenticating.

Example configuration snippet:

[sut.foo]
tracker=fuzzinator.tracker.GithubTracker

[sut.foo.tracker]
repository=alice/foo
token=1234567890123456789012345678901234567890

class fuzzinator.tracker.GitlabTracker(*args, **kwargs)¶

GitLab issue tracker.

Mandatory parameters of the issue tracker:

url: URL of the GitLab installation.

project: repository name in user/repo format.

Optional parameter of the issue tracker:

private_token: a personal access token for authenticating.

Example configuration snippet:

[sut.foo]
tracker=fuzzinator.tracker.GitlabTracker

[sut.foo.tracker]
url=https://gitlab.example.org
project=alice/foo
private_token=12345678901234567890

class fuzzinator.tracker.MonorailTracker(*args, **kwargs)¶

Monorail issue tracker.

Mandatory parameters of the issue tracker:

project_id: ID (name) of the project.

issue_labels: a list of labels (strings) to use when reporting an issue.

issue_status: the status to use when reporting an issue.

Example configuration snippet:

[sut.foo]
tracker=fuzzinator.tracker.MonorailTracker

[sut.foo.tracker]
project_id=foomium
issue_labels=["Pri-3", "Type-Bug"]
issue_status=Untriaged

class fuzzinator.tracker.Tracker(*args, **kwargs)¶

An abstract base class for issue trackers where issues can be reported to.

find_duplicates(*, title)¶

Query for potential duplicates of an issue in the tracker based on the similarity of titles.

Return an empty list by default.

Parameters:: title (str) – A string to query the tracker for. The short string representation of the issue as returned by its Formatter.
Returns:: A list of tuples, where each tuple contains the URL and a short description (title) of the potential duplicate in the tracker.
Return type:: list[tuple[str, str]]
Raises:: TrackerError – If the query cannot be performed.

report_issue(*, title, body)¶

Report an issue to the tracker.

Raises NotImplementedError by default.

Parameters:

title (str) – The short description to use when reporting the issue to the tracker. Potentially the short string representation of the issue as returned by its Formatter, but may have been edited by the user.
body (str) – The full issue report to send to the tracker. Potentially the long string representation of the issue as returned by its Formatter, but may have been edited by the user.

Returns:

The URL of the reported issue.

Return type:

str

Raises:

TrackerError – If the issue cannot be reported.

Subclasses may extend the signature of this method in overridden versions. In that case, they should also define UI extensions that collect input from the user that will be passed to the extra arguments (see: ui_extension, and fuzzinator.ui.tui.ReportDialog.data or report.html).

settings()¶

Return tracker-specific information. This method is to be used by trackers that need UI extensions to collect extra input from the user when reporting an issue and need some tracker-specific information to build the UI extension (see ui_extension, and fuzzinator.ui.tui.ReportDialog.init or report.html).

Return None by default.

Returns:: Tracker-specific information.
Return type:: Any

ui_extension = {}¶

A dictionary to reference UI extensions for the tracker (if it needs any).

If it contains the key 'tui', then the associated value must be the fully qualified name of a subclass of fuzzinator.ui.tui.ReportDialog. That specialized dialog will be used by the text-based UI to prepare the report of an issue with this tracker.

If it contains the key 'wui', then the associated value must either be an absolute file path (formatted as /path/to/file) or a reference to a resource in a package (formatted as //package.module/path/to/file), naming a child template of report.html. That specialized template page will be used by the web UI to prepare the report of an issue with this tracker.

See UI Extensions.

exception fuzzinator.tracker.TrackerError¶: Raised when a Tracker operation cannot be performed.

UI Extensions¶

class fuzzinator.ui.tui.ReportDialog(*, issue, config, db)¶

Base class of dialogs that allow preparing an issue report on the Urwid/text-based UI.

Notes:

A new dialog is instantiated for every report.

Instead of __init__, the init method must be overridden in subclasses.

data()¶

Return a dictionary that contains data that shall be reported to the issue tracker. The items in the dictionary will be passed as keyword arguments to fuzzinator.tracker.Tracker.report_issue. Therefore, the dictionary must contain values with keys 'title' and 'body'.

The default operation is to return a dictionary that contains the (potentially user-edited) short and full string representations of the issue-to-be-reported assigned to 'title' and 'body', respectively.

Subclasses may override this method, where they call this original operation to build the default dictionary and then extend it with additional fields (usually with information coming from extra UI elements set up in init), as expected by the corresponding Tracker.

Returns:: the data to be reported to the issue tracker.
Return type:: dict

init()¶

This method is called to finish initialization after __init__ sets up the basic layout of the dialog. Subclasses shall override this method if they want to add extra UI elements to the dialog to get input from the user that is necessary to submit the issue report to the tracker.

This method is a no-op by default, therefore subclasses don’t have to invoke it from the overridden version.

Information about the issue to be reported and about the tracker, and UI extension points are available as instance variables.

Variables:

issue (dict[str, Any]) – the issue to be reported.
settings (Any) – the tracker-specific information returned by fuzzinator.tracker.Tracker.settings.
settings_walker (urwid.SimpleListWalker) – a list that can be extended with Urwid UI components to display information to and collect input from the user, usually based on settings (empty by default).

template report.html

Parent template of pages that allow preparing an issue report on the Tornado-based web UI. To be extended using {% extends "report.html" %}.

Child templates can extend report.html at two points:

{% block report_head %}

A replaceable block in the <head> element where child templates can put <script> elements and extra logic (empty by default).

{% block settings %}

A replaceable block in the report form of the issue report page where child templates can put extra UI/form elements (empty by default).

When reporting the issue, the form data is automatically collected and posted via the web API to fuzzinator.tracker.Tracker.report_issue. (The name attributes of the form elements become the names of the keyword arguments of report_issue.) The report form already contains elements with name="title" and name="body" (outside the settings block).

Some information is available to the templates as variables in their namespace:

settings: The tracker-specific information returned by fuzzinator.tracker.Tracker.settings.

Issue Trackers: package fuzzinator.tracker¶

UI Extensions¶

Issue Trackers: package `fuzzinator.tracker`¶