Merge branch 'dev' into unittest-plots

Author: Jayantparashar10

.agents/context/backend.md

@@ -14,7 +14,7 @@
 ## Coding Rules
 
 - Follow PEP 8, format with `black py` (v23.1.0), 80-char lines
-- Python >= 3.8 compatibility
+- Python >= 3.12 compatibility
 - Use `@pytorch_wrap` on all `Visdom` methods
 - Use `warn_once()` for deprecation warnings
 

.agents/context/testing.md

@@ -1,8 +1,20 @@
 # Testing Instructions
 
-Cypress 9 for E2E and visual regression. No Python unit tests — validation is via demo scripts and Cypress.
+Two layers: **pytest** for Python unit tests (pure functions, server utils, window/env lifecycle) and **Cypress 9** for E2E and visual regression. Demo scripts remain useful for manual/visual validation.
 
-## Run Tests
+## Run Python Tests (pytest)
+
+```bash
+pip install -r test-requirements.txt   # includes pytest, pytest-cov
+pytest                                 # runs the tracked suite under py/tests/
+pytest -m "not server"                 # skip tests that need a live server (CI default)
+```
+
+Config lives in `pyproject.toml` (`[tool.pytest.ini_options]`): discovery is scoped to
+`py/tests/` and `pythonpath = ["py"]` makes `import visdom` work without an editable install.
+Experimental `test_*.py` scripts in the repo root (and `test/`) are intentionally out of scope.
+
+## Run E2E / Visual Tests (Cypress)
 
 ```bash
 visdom -port 8098 -env_path /tmp   # Always start fresh server first
@@ -24,9 +36,19 @@ Always use port `8098` and `-env_path /tmp` for isolation.
 
 `basic.js` (connection), `pane.js` (CRUD), `text.js`, `image.js`, `properties.js`, `modal.js`, `misc.js`, `screenshots.init.js` (baseline), `screenshots.js` (comparison).
 
+## Writing Python Tests
+
+- Place in `py/tests/`, name files `test_*.py`, classes `Test*` (unittest `TestCase` or plain
+  pytest functions both work — pytest auto-discovers unittest).
+- Keep them hermetic (no running server). A test that genuinely needs a live server must be
+  marked `@pytest.mark.server` so CI can deselect it.
+- Start with simple hermetic tests (e.g., `test_smoke.py`) and add focused unit tests for
+  server/window/env lifecycle code as coverage grows.
+
 ## CI
 
-- Python 3.8, 3.9, 3.10 matrix, both WebSocket and polling modes
+- `python-tests.yml` runs `pytest -m "not server"` on a Python version matrix for every pull
+  request (and on pushes to master/dev)
 - Visual regression compares PR screenshots against base branch
 - `update-js-build-files.yml` auto-compiles JS on master
 - `pypi.yml` publishes to PyPI when VERSION changes

.github/actions/prepare/action.yml

@@ -12,7 +12,7 @@ inputs:
   python-version:
     description: 'Python version to use'
     required: false
-    default: '3.10'
+    default: '3.12'
 
 runs:
   using: "composite"

.github/workflows/deploy-docs.yml

@@ -52,4 +52,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128

.github/workflows/process-changes.yml

@@ -154,7 +154,7 @@ jobs:
     needs: install-and-build
     strategy:
       matrix:
-        python: ['3.10', '3.11', '3.12']
+        python: ['3.12', '3.13']
     steps:
       - name: "Checkout Repository"
         uses: actions/checkout@v7.0.0
@@ -202,3 +202,27 @@ jobs:
         with:
           name: cypress-screenshots-functional-polling
           path: cypress/screenshots
+
+  playwright-test:
+    name: "Playwright Functional Test"
+    runs-on: ubuntu-latest
+    needs: install-and-build
+    steps:
+      - name: "Checkout Repository"
+        uses: actions/checkout@v7.0.0
+      - uses: ./.github/actions/prepare
+
+      - name: Install Playwright Chromium
+        run: npx playwright install --with-deps chromium
+
+
+
+      - name: Run Playwright tests
+        run: npm run test:pw
+
+      - name: Upload Playwright Report
+        uses: actions/upload-artifact@v7
+        if: failure()
+        with:
+          name: playwright-report
+          path: playwright/playwright-report/

.github/workflows/python-tests.yml

@@ -0,0 +1,31 @@
+name: Python Tests
+
+on:
+  pull_request:
+  push:
+    branches:
+      - master
+      - dev
+
+jobs:
+  pytest:
+    name: "pytest (Python ${{ matrix.python-version }})"
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v7.0.0
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package and test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .
+          python -m pip install -r test-requirements.txt
+      - name: Run pytest
+        run: pytest -m "not server"

.gitignore

@@ -30,3 +30,10 @@ website/.docusaurus
 venv
 test-bin
 bin
+
+playwright/playwright-report/
+playwright/test-results/
+playwright/tmp/
+playwright-report/
+test-results/
+tmp/

AGENTS.md

@@ -4,7 +4,7 @@
 # AGENTS instructions
 
 Visdom: Python client + Tornado server + React frontend for live data visualization.
-Version `0.2.4` · Python >= 3.8 · Apache 2.0
+Version `0.2.4` · Python >= 3.12 · Apache 2.0
 
 ## Setup
 
@@ -38,14 +38,15 @@ Version `0.2.4` · Python >= 3.8 · Apache 2.0
 
 ## Testing
 
-- Start server: `visdom -port 8098 -env_path /tmp`
+- Python unit tests: `pytest -m "not server"` (config in `pyproject.toml`, suite in `py/tests/`)
+- Start server (for Cypress): `visdom -port 8098 -env_path /tmp`
 - Baseline: `npm run test:init`
-- Run tests: `npm run test`
+- Run E2E tests: `npm run test`
 - Pre-commit: `pre-commit run --all-files`
 
 ## PR Checklist
 
-- Branch from `master`, add Cypress tests for new code
+- Branch from `master`; add `pytest` tests in `py/tests/` for Python code and Cypress tests for frontend behavior
 - Update `README` for API changes, `__init__.pyi` for interface changes
 - Run linters, do not commit `py/visdom/static/`
 

CONTRIBUTING.md

@@ -193,13 +193,19 @@ To run the predefined tests
 5. run `npm run test:gui` (a new window should appear)
 6. click through the test spec-files and observe the tests done automatically in a newly opened browser instance
 
-**as CLI tests**:
+**as CLI tests (Cypress)**:
 1. start a fresh visdom server instance on port `8098` , i.e. by just calling `visdom -port 8098` (Just to make sure another instance is not interfering with our test.)
 2. run `npm run test:init`. This generates screenshots of all plots for the visual regression testing.
 3. Adapt the code now to your needs.
 4. run `npm run build` *or* `npm run dev` (enables automatic building)
 5. run `npm run test`
 
+**using Playwright (E2E tests)**:
+1. start a fresh visdom server instance on port `8098` using your environment's Python, i.e. `python -m visdom.server -port 8098 -env_path playwright/tmp` (make sure no other instances interfere).
+2. run `npx playwright install chromium` on first setup to install the browser.
+3. run `npm run build` *or* `npm run dev` to compile the frontend code.
+4. run the Playwright test suite: `npm run test:pw`
+
 ## Issues
 We use GitHub issues to track public bugs. Please ensure your description is
 clear and has sufficient instructions to be able to reproduce the issue.

README.md

@@ -267,6 +267,7 @@ Other options are either currently unused (endpoint, ipv6) or used for internal
 ### Basics
 Visdom offers the following basic visualization functions:
 - [`vis.image`](#visimage)    : image
+- [`vis.image_heatmap`](#visimageheatmap) : image with heatmap overlay
 - [`vis.images`](#visimages)   : list of images
 - [`vis.text`](#vistext)     : arbitrary HTML
 - [`vis.properties`](#visproperties)     : properties grid
@@ -285,8 +286,10 @@ The following API is currently supported:
 - [`vis.scatter`](#visscatter)  : 2D or 3D scatter plots
 - [`vis.sunburst`](#vissunburst)  : sunburst (hierarchy) charts
 - [`vis.line`](#visline)     : line plots
+- [`vis.learning_curve`](#vislearning_curve) : named training metric curves
 - [`vis.stem`](#visstem)     : stem plots
 - [`vis.heatmap`](#visheatmap)  : heatmap plots
+- [`vis.confusion_matrix`](#visconfusion_matrix)  : confusion matrix plots
 - [`vis.bar`](#visbar)  : bar graphs
 - [`vis.histogram`](#vishistogram) : histograms
 - [`vis.histogram2d`](#vishistogram2d) : 2D histograms (density maps)
@@ -295,8 +298,11 @@ The following API is currently supported:
 - [`vis.pie`](#vispie)      : pie charts
 - [`vis.surf`](#vissurf)     : surface plots
 - [`vis.contour`](#viscontour)  : contour plots
+- [`vis.roc_curve`](#visroc_curve)  : ROC curves
+- [`vis.pr_curve`](#vispr_curve)  : precision-recall curves
 - [`vis.quiver`](#visquiver)   : quiver plots
 - [`vis.mesh`](#vismesh)     : mesh plots
+- [`vis.sankey`](#vissankey)   : sankey (flow) diagrams
 - [`vis.dual_axis_lines`](#visdual_axis_lines)     : double y axis line plots
 - [`vis.graph`](#visgraph)    : network graphs
 
@@ -353,6 +359,34 @@ The following `opts` are supported:
 > **Note** You can use alt on an image pane to view the x/y coordinates of the cursor. You can also ctrl-scroll to zoom, alt scroll to pan vertically, and alt-shift scroll to pan horizontally. Double click inside the pane to restore the image to default.
 
 
+#### vis.image_heatmap
+
+This function overlays a saliency or attention heatmap on top of an image. It takes a `CxHxW` or `HxW` array `img` (uint8 or float) and an `HxW` float array `heatmap` with values in `[0, 1]`. The blending is per-pixel — pixels where the heatmap is near zero stay close to the original image, so a zero-gradient background does not get tinted by the colormap.
+
+```python
+import numpy as np
+from visdom import Visdom
+
+viz = Visdom()
+
+# img: CxHxW uint8 or float in [0, 1]
+# heatmap: HxW float in [0, 1] — e.g. from a saliency method or attention map
+viz.image_heatmap(img, heatmap, opts=dict(title="Saliency", alpha=0.6, colormap="jet"))
+```
+
+Any attribution method that produces an `HxW` numpy array works — gradient saliency, GradCAM, SHAP, or a hand-computed attention map.
+
+The following `opts` are supported:
+
+- `alpha`: blend strength (`float` in `[0, 1]`; default = `0.5`). Higher values make the heatmap more visible.
+- `colormap`: matplotlib colormap name (`string`; default = `'jet'`). Falls back to a blue-red gradient if matplotlib is not installed.
+- `caption`: caption for the image pane
+- `jpgquality`: JPG quality (`number` 0-100). If set, the result is encoded as JPEG. Otherwise PNG.
+- `normalize`: normalize the image to `[0, 1]` before blending (`boolean`; default = `False`)
+
+> **Note** `heatmap` accepts any finite float range. Values outside `[0, 1]` are rescaled automatically via min-max normalization, so methods like SHAP or Integrated Gradients that return signed or unnormalized values work without any pre-processing. NaN maps to 0; infinite values are clamped to the `[0, 1]` boundary.
+
+
 #### vis.images
 
 This function draws a list of `images`. It takes an input `B x C x H x W` tensor or a `list of images` all of the same size. It makes a grid of images of size (B / nrow, nrow).
@@ -548,6 +582,57 @@ The following `opts` are supported:
 - `opts.traceopts`   : `dict` mapping trace names or indices to `dict`s of additional options that plot.ly accepts for a trace.
 - `opts.webgl`       : use WebGL for plotting (`boolean`; default = `false`). It is faster if a plot contains too many points. Use sparingly as browsers won't allow more than a couple of WebGL contexts on a single page.
 
+#### vis.roc_curve
+This function draws a ROC curve for binary classification.
+
+It accepts either:
+- raw binary labels and scores via `y_true` and `y_score`, or
+- precomputed curve points via `fpr` and `tpr`.
+
+The following `opts` are supported:
+- `opts.title`      : plot title (`string`; default includes ROC-AUC)
+- `opts.legend`     : two legend labels for curve and baseline (`list`)
+- `opts.xlabel`     : x-axis label (`string`; default = `False Positive Rate`)
+- `opts.ylabel`     : y-axis label (`string`; default = `True Positive Rate`)
+- `opts.layoutopts` : additional backend layout options (`dict`)
+
+#### vis.pr_curve
+This function draws a precision-recall curve for binary classification.
+
+It accepts either:
+- raw binary labels and scores via `y_true` and `y_score`, or
+- precomputed curve points via `precision` and `recall`.
+
+The following `opts` are supported:
+- `opts.title`      : plot title (`string`; default includes PR-AUC)
+- `opts.legend`     : two legend labels for curve and baseline (`list`)
+- `opts.xlabel`     : x-axis label (`string`; default = `Recall`)
+- `opts.ylabel`     : y-axis label (`string`; default = `Precision`)
+- `opts.layoutopts` : additional backend layout options (`dict`)
+
+
+#### vis.learning_curve
+This function draws named machine-learning metrics as line plots. It accepts a mapping from metric names to scalar values or equal-length 1D series and forwards to [`vis.line`](#visline).
+
+For example:
+
+```python
+win = vis.learning_curve(
+    {"train_loss": [1.0, 0.8, 0.6], "val_loss": [1.1, 0.9, 0.7]},
+    step=[1, 2, 3],
+    env="training",
+    opts={"title": "Loss", "ylabel": "loss"},
+)
+
+vis.learning_curve(
+    {"train_loss": 0.55, "val_loss": 0.68},
+    step=4,
+    win=win,
+    env="training",
+    update="append",
+)
+```
+
 
 #### vis.stem
 This function draws a stem plot. It takes as input an `N` or `NxM` tensor
@@ -578,6 +663,32 @@ The following `opts` are supported:
 - `opts.layoutopts` : `dict` of any additional options that the graph backend accepts for a layout. For example `layoutopts = {'plotly': {'legend': {'x':0, 'y':0}}}`.
 - `opts.nancolor`   : color for plotting `NaN`s. If this is `None`, `NaN`s will be plotted as transparent. (`string`; default = `None`)
 
+#### vis.confusion_matrix
+This function draws a confusion matrix for classification evaluation.
+
+It accepts either:
+- raw label vectors via `y_true` and `y_pred`, or
+- a precomputed confusion matrix via `cm`.
+
+Optional normalization can be applied with the `normalize` parameter:
+- `'true'`: normalize by row (actual class)
+- `'pred'`: normalize by column (predicted class)
+- `'all'`: normalize by total count
+
+An existing confusion matrix window can be modified with the `update` parameter:
+- `'replace'`: redraw the whole matrix in the window given by `win`
+- `'remove'`: delete the window given by `win`
+
+The following `opts` are supported:
+
+- `opts.title`       : plot title (`string`; default = `Confusion Matrix`)
+- `opts.xlabel`      : x-axis label (`string`; default = `Predicted`)
+- `opts.ylabel`      : y-axis label (`string`; default = `Actual`)
+- `opts.colormap`    : Plotly colorscale (`string`; default = `Blues`)
+- `opts.showCounts`  : show raw counts in cells (`bool`; default = `True`)
+- `opts.showPercent` : show percentages in cells (`bool`; default = `True` when normalized, `False` otherwise)
+- `opts.layoutopts`  : `dict` of any additional options that the graph backend accepts for a layout.
+
 #### vis.bar
 This function draws a regular, stacked, or grouped bar plot. It takes as
 input an `N` or `NxM` tensor `X` that specifies the height of each of the
@@ -696,6 +807,27 @@ The following `opts` are supported:
 - `opts.opacity`: opacity of polygons (`number` between 0 and 1)
 - `opts.layoutopts`  : `dict` of any additional options that the graph backend accepts for a layout. For example `layoutopts = {'plotly': {'legend': {'x':0, 'y':0}}}`.
 
+#### vis.sankey
+This function draws a Sankey (flow) diagram. Flows are defined by three
+equal-length arrays:
+
+- `source`: source node index of each link (`N` array of ints)
+- `target`: target node index of each link (`N` array of ints)
+- `value` : magnitude of each link (`N` array of non-negative numbers)
+
+`labels` is an optional list of node names. If omitted, nodes are referenced
+by their index alone.
+
+The following `opts` are supported:
+
+- `opts.labels`     : list of node labels (alternative to the `labels` arg)
+- `opts.pad`        : node padding in px (`number`; default = 15)
+- `opts.thickness`  : node thickness in px (`number`; default = 20)
+- `opts.orientation`: `'h'` (default) or `'v'`
+- `opts.nodecolor`  : node color(s) (`string` or list of strings)
+- `opts.linkcolor`  : link color(s) (`string` or list of strings)
+- `opts.layoutopts` : `dict` of any additional options that the graph backend accepts for a layout.
+
 #### vis.dual_axis_lines
 This function will create a line plot using plotly with different Y-Axis.
 
@@ -857,7 +989,7 @@ visdom is Apache 2.0 licensed, as found in the LICENSE file.
 Support for Lua Torch was deprecated following `v0.1.8.4`. If you'd like to use torch support, you'll need to download that release. You can follow the usage instructions there, but it is no longer officially supported.
 
 ## Contributing
-See guidelines for contributing [here.](./CONTRIBUTING.md)
+See guidelines for contributing and running E2E/visual tests (Cypress and Playwright) [here.](./CONTRIBUTING.md)
 
 ## Acknowledgments
 Visdom was inspired by tools like [display](https://github.com/szym/display) and relies on [Plotly](https://plot.ly/) as a plotting front-end.