User guidelines¶

Here is a quick user introduction to Dragnet.

Requirements¶

Ruby 2.7.0 or greater:: Recommended Ruby (MRI) < 3.0
RubyGems 3.0.0 or greater:: Normally installed by default with Ruby.
Git 2.0.0 or greater:: Must be installed in the system and the git executable should be in the PATH.
unix-like operating system:: The tool can run in all systems (provided that the Ruby interpreter is available) but to avoid issues with paths and file names a *nix (ex. Linux, Macintosh, BSD, etc) operating system is recommended.

Installation¶

Dragnet is a Ruby Gem. After installing the gem you can use the CLI to execute the tool.

To install dragnet tool:

gem install dragnet

Needed configuration¶

Dragnet needs a configuration to run, the configuration has to contain the path(s) where the MTRs are located.

Example of configuration file content:

# .dragnet.yaml

glob_patterns:
    - manual/*.yaml

The MTR files have to contain the information regarding each specific MTR:

MTR Attributes¶
#	Parameter	Key	Value	Required
1	ID	`id`	The ID of the MTR	Yes
2	Result	`result`	The result of the Manual Test.	Yes
3	SHA1	`sha1`	The SHA1 of the commit in which the Manual Test was performed.	Yes
4	Name	`name`	The name of the person who performed the Manual Test.
5	Description	`description`	The description of the Manual Test, normally which actions were performed and what it was mean to test.
6	Files	`files`	The files involved in the MTR, these are the files which will be checked for changes when evaluating the validity of the MTR.	Either `files` or `repos` should be present, not both.
7	Repositories	`repos`	An array of Hashes with the information about the repositories that are involved in the MTR, these repositories will be checked for changes during the evaluation of the MTR.	Either `files` or `repos` should be present, not both.
8	Review Status	`review_status`	The review status of the MTR. (Normally changed when someone other than the tester verifies the result of the Manual Test)
9	Review comments	`review_comments`	The comments left by the person who performed the review of the Manual Test.
10	Findings	`findings`	The findings that the reviewer collected during the review process (if any).
11	Test method	`test_method`	The method(s) used to carry out the test.
12	Test case derivation mathod	`tc_derivation_method`	The method(s) used to derive the test case, note either files or repos should be present, not both.

The repo array structure:

#	Parameter	Key	Value	Required
1	Path	`path`	The path where the repository is stored.	Yes
2	SHA1	`sha1`	The SHA1 the repository had when the MTR was created.	Yes
3	files	`files`	The file or array of files covered by the MTR.

Dragnet tool usage¶

To use Dragnet use the CLI to launch the tool, the tool accepts the following arguments:

Commands

dragnet –version: Prints the current version of the Gem
dragnet –help [COMMAND]: Describes available commands or one specific COMMAND
dragnet check [OPTIONS] [PATH]: Executes the verify procedure on the given PATH. If PATH is not present, this defaults to the value of the path key in the configuration file or the current working directory if the later is also missing.

Options

--export

If given, the results of the verification procedure will be exported to the given file. The format of the export will be deducted from the given file’s name. (HTML and JSON formats are currently supported) The switch can be used multiple times to produce multiple output files.

--multi-repo

Enables the multi-repo compatibility mode. This prevents Dragnet from assuming that [PATH] refers to a Git repository allowing it to run even if that is not the case.

Using this option will cause Dragnet to raise an error if it finds a MTR which doesn’t have a repos attribute.

--quiet

Suppresses the log messages (except errors).

Example of usage:

dragnet check --export dragnet.html .

Output:

Dragnet will produce the following output:

A log of the executed operations and abnormal conditions. The logs will always go to the Standard Output. (Logs can be suppressed with the --quiet command line switch).
When the --export command line switch is used, Dragnet exports the results of the execution to the given format.
Dragnet’s process will finish with a particular exit code, which reflects the result of the execution. The list of Possible exit codes can be found here.