Usage
=====

The ``pytest-html-plus`` VS Code extension is designed to help you **navigate failed pytest tests directly inside the editor**, using the JSON report generated by ``pytest-html-plus``.

It does not run tests or generate reports. It consumes an existing report artifact.

Prerequisites
--------------

- VS Code
- ``pytest-html-plus`` installed in your test environment
- A generated ``final_report.json`` file

Generating or Obtaining the Report
---------------------------------

The VS Code extension consumes an existing ``final_report.json`` (by default in the project root, unless configured otherwise).file generated by ``pytest-html-plus``.

You can obtain this report in either of the following ways:

Local test runs
^^^^^^^^^^^^^^^

Run pytest with ``pytest-html-plus`` enabled as usual. For example::

    pytest

This produces a ``final_report.json`` file (by default in the project root, unless configured otherwise).

CI artifacts
^^^^^^^^^^^^

If tests were executed in CI, you can download the CI artifact containing ``final_report.json`` (unless name configured otherwise). and place it anywhere in your workspace.

Once the file is available locally, configure the extension to point to it. The extension does not require the tests to have been run inside VS Code.


Installing the Extension
------------------------

Install **Pytest HTML Plus** from the VS Code Marketplace.

Once installed, a **ReporterPlus** icon will appear in the Activity Bar.

Opening the Sidebar
-------------------

1. Open your project folder in VS Code
2. Click the **ReporterPlus** icon in the Activity Bar
3. The sidebar will open and attempt to read the configured report

Configuring the Report Path
---------------------------

If no report is configured, the sidebar will prompt you to configure one.

You can configure the report path in one of the following ways:

- Browse and select ``final_report.json`` (by default in the project root, unless configured otherwise).
- Enter the path manually
- Auto-detect reports within the workspace (Detects only when json file exists with name ``final_report.json``)

The selected path is stored at the workspace level.

Viewing Failed Tests
--------------------

Once configured, the sidebar displays:

- A summary of total, passed, failed, and skipped tests
- Failed tests grouped by file
- Inline error context (when available)

Only failed tests are emphasized by default.

Navigating to Failures
----------------------

Clicking a failed test in the sidebar will:

- Open the corresponding test file
- Move the cursor directly to the failure line

This allows you to move from failure to fix without scanning terminal output.

Refreshing the View
-------------------

After re-running tests, click **Refresh** in the sidebar to reload the report.

The extension always reads the latest contents of ``final_report.json``. (by default in the project root, unless configured otherwise).

Design Notes
------------

- The extension is **report-driven**, not runner-driven
- It works regardless of where pytest was executed (local, CI, xdist, containers)
- It complements the HTML report instead of replacing it

For detailed inspection, screenshots, and CI artifacts, continue using the HTML report generated by ``pytest-html-plus``.