stackviz/doc/source/man/stackviz-front.rst

===================
AngularJS Front-end
===================

The AngularJS front-end uses config files generated by :code:`stackviz-export`
to display a variety of information regarding test runs. This document breaks
down the various components of the Stackviz Angular app.

Pages
=====

----
Home
----
:Path: <host>/#/
:Directive: :code:`./app/views/home.html`
:Controller: :code:`./app/js/controllers/home.js`

The landing page for Stackviz consists of two elements. The first is a summary
panel that shows statistics for the run including runtime (MM:SS), total number
of tests run, number of failed tests, and number of skipped tests. The button
in the footer of this panel links to the timeline, where individual tests can
be browsed further. The second element is a panel showing all of the failures
for the current run, including the last few lines of their tracebacks. The test
divs here link to their corresponding Test Details page.

--------
Timeline
--------
:Path: <host>/#/<run>/timeline?test=<test>/
:Directive: :code:`./app/views/timeline.html`
:Controller: :code:`./app/js/controllers/timeline.js`

The Timeline provides an overview of all the tests that were executed as part
of a run. Each lane in the timeline corresponds to one worker thread on the
host machine. Each rectangle in the timeline represents one test. When a
rectangle is selected, the details panel below the timeline is populated with
information about the test. Each test rectangle is also color-coordinated:
green is passing, blue is skipped, and red is failed.

The details panel below the timeline shows information pertaining to the
current test (it is empty if no test is selected): test class, test module,
which worker executed it, the duration, and start & finish timestamps. The
footer contains a button that links to the test details page for the selected
test.

------------
Test Details
------------
:Path: <host>/#/<run>/test-details/<test>/
:Directive: :code:`./app/views/test-details.html`
:Controller: :code:`./app/js/controllers/test-details.js`

The test details page consists of one panel that displays various log info
from one test. The first tab contains summary information similar to the info
found on the test panel on the timeline. Additional tabs in this panel
are dependent upon the logs that the test kept. Each of these tabs provides
additional information to aid debugging. The most common tabs include:

  **pythonlogging**
      Contains logs for API calls that were used in the test. This
      log is often quite large, as it contains full headers for every request
      at INFO, DEBUG, WARNING, and ERROR levels. To make searching these logs
      easier, the test details page has a built in filter for parsing by log
      level. In the header of the test details page, the magnifying glass
      can be clicked to only show pythonlogging lines that correspond to a
      certain level of detail. To find errors in pythonlogging quickly, it is
      advisable to only select the WARNING and ERROR levels for display.

  **reason**
      Only available for skipped tests. Lists the reason for skipping the test,
      usually to avoid triggering an outstanding bug.

  **traceback**
      Only available for failed tests. Shows the full traceback of the test
      runner's error output when the test failed. This is useful in quickly
      isolating the cause of a failure. There can be multiple traceback logs
      (e.g. traceback, traceback1) for one test.

When enough information has been gleaned from more detailed logs, the button
in the panel filter can be used to quickly navigate back to the timeline page.

Directives
==========

**tempestSummary**
    The tempest summary directive consists of one panel that shows stats for
    one run: Duration of the run, number of tests run, number of tests skipped,
    and number of tests failed. :code:`timeDiff` (the duration of the run) is
    calculated from the start and end timestamps contained in summary data.
    All other fields are populated directly from the summary data, via a call
    to the dataset service.

**testDetailsSearch**
    :code:`testDetailsSearch` uses two HTML pages to search the test details
    page: :code:`test-details-search-popover.html` and :code:`test-details-search.html`.
    The popover contains the filter levels for the :code:`pythonlogging` tab:
    INFO, DEBUG, WARNING, ERROR. This directive is used as the template for
    :code:`test-details-search`, per AngularJS popover convention. The function
    used to parse the logs, :code:`parsePythonLogging` actually lives in the
    controller for testDetailsSearch, and is passed through both the prior
    directives' scopes. This function reads in the :code:`pythonLogging` tab
    as one text object, then splits it by :code:`\n` to create an array of
    lines. Each line is then added back to the :code:`pythonLogging` tab if it
    contains the specific log level somewhere in the line.

**timeline**
    The timeline directive is a container for the actual timeline components,
    detailed below.

**timelineDetails**

**timelineDstat**

**timelineOverview**

**timelineSearch**

**timelineViewport**


Services
========

**dataset**
    The dataset service is an API that provides the front-end with all of the
    data generated by :code:`stackviz-export`. All data processed by
    :code:`stackviz-export` ends up in the `./app/data/` directory to be called
    by dataset service with :code:`$http` and :code:`$q` directives. Below is
    the list of calls:
        - :code:`list` returns `config.json` using GET.
        - :code:`get(id)` calls :code:`list`, then iterates through all the
          available datasets for the requested id number. Rejects if not found.
        - :code:`raw(dataset)` returns `<dataset>_raw.json` file using GET.
        - :code:`details(dataset)` returns `<dataset>_details.json` file using GET.
        - :code:`tree(dataset)` returns `<dataset>_tree.json` file using GET.
        - :code:`dstat(dataset)` returns `dstat_log.csv` file using GET, if available.

**progress**
    A wrapper for :code:`nprogress`, a progress bar library. Used in the timeline
    and test details pages to show progress in loading datasets.