Managing Bugs

BugZoo packages historical software versions as lightweight, immutable Docker container images. The bugs registered with a BugZoo server may be accessed via the the BugZoo client’s bugs property, which exposes a BugManager. Each bug is represented by an immutable Bug instance. The [] operator may be used to fetch a Bug instance for a bug with a given name. The names of all of the bugs registered with the server can be accessed by iterating over the BugManager, as shown below.

for name in client_bugzoo.bugs:
  bug = client_bugzoo.bugs[name]  # type: Bug

The BugManager can be used to build Docker images for bugs according to the instructions provided in the bug’s manifest:

bug = client_bugzoo.bugs['manybugs:python:69223-69224']
client_bugzoo.bugs.build(bug)

Alternatively, prebuilt images may be downloaded from DockerHub via the download method:

client_bugzoo.bugs.download(bug)

The BugManager may also be used to instruct the BugZoo server to uploaded the Docker image for a given scenario to DockerHub:

client_bugzoo.bugs.upload(bug)

Docker images may be removed from the server by using the uninstall method:

client_bugzoo.bugs.uninstall(bug)

The is_installed method may be used to determine whether the Docker image for a given bug has been installed onto the server:

if client_bugzoo.bugs.is_installed(bug):
  print("the image is installed! :-)")
else:
  print("the image is not installed :'(")

The BugManager may also be used to dynamically register ephemeral Bug descriptions. Once the server is closed, these descriptions will be destroyed. In general, we suggest that users register bugs with the server via the command-line interface. However, there are cases where a dynamic bug registration is preferable, such as mutation testing, where a new Bug instance can be created for every mutation.

bug = Bug(name="mytemporarybug", ...)
client_bugzoo.bugs.register(bug)

Bugs may also be dynamically deregistered via the del operator, as shown below. Note that the del operator will not permanently remove bugs that are associated with a source (i.e., bugs that have been added via the command line). In the case of such bugs, the del operator will hide their existence for the remaining lifetime of the server.

del client_bugzoo.bugs["mytemporarybug"]

API Reference

class Bug

Bugs provide an immutable snapshot of a software system at a given point in time, allowing it to be empirically studied and inspected in a transparent and reproducible manner.

harness → TestSuite

class BugManager

Provides access to the historical bugs that are registered with the server. Can be used to install, download, and uninstall registered bugs, or to dynamically register new bugs with the server.

__getitem__(name: str) → bugzoo.core.bug.Bug

Retrieves the bug registered under a given name.

Raises

KeyError – if no bug is found with the given name.

__iter__() → Iterator[str]

Returns an iterator over the names of the bugs registered with the server.

is_installed(bug: bugzoo.core.bug.Bug) → bool

Determines whether the Docker image for a given bug has been installed on the server.

build(bug: bugzoo.core.bug.Bug)

Instructs the server to build the Docker image associated with a given bug.

download(bug: bugzoo.core.bug.Bug) → bool

Instructs the server to download the Docker image associated with a given bug from DockerHub.

uninstall(bug: bugzoo.core.bug.Bug) → bool

Uninstalls the Docker image associated with a given bug.

upload(bug: bugzoo.core.bug.Bug) → bool

Instructs the server to upload the Docker image associated with a given bug to DockerHub.

register(bug: bugzoo.core.bug.Bug) → None

Dynamically registers a given bug with the server. Note that the registration will not persist beyond the lifetime of the server. (I.e., when the server is closed, the bug will be deregistered.)

Raises

BugAlreadyExists – if there is already a bug registered on the server under the same name as this bug.