Merge branch 'dev' into feat/image-heatmap

Author: Jayantparashar10

.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/workflows/process-changes.yml

@@ -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

@@ -38,14 +38,15 @@ Version `0.2.4` · Python >= 3.12 · 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

@@ -286,6 +286,7 @@ 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
@@ -297,6 +298,8 @@ 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
@@ -579,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
@@ -935,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.

REFACTORING.md

@@ -212,7 +212,7 @@ Phases 1 & 2 can start immediately in parallel. Phase 5 can proceed independentl
 ## Verification Plan
 
 For each phase:
-1. Run existing tests: `cd py && python -m pytest ../test/`
+1. Run existing tests: `python -m pytest` (config in `pyproject.toml`; suite lives in `py/tests/`)
 2. Run Cypress E2E: `npm run test` (server on port 8098)
 3. Manual smoke test: `python -m visdom.server -port 8098` then run `example/demo.py`
 4. Verify no regressions in visual regression screenshots

cypress/integration/pane.js

@@ -9,12 +9,15 @@ const basic_examples = [
   ['Bar Plot', 'plot_bar_basic'],
   ['Scatter Plot', 'plot_scatter_basic'],
   ['Surface Plot', 'plot_surface_basic'],
+  ['ROC Curve', 'plot_roc_curve'],
+  ['PR Curve', 'plot_pr_curve'],
   ['Box Plot', 'plot_special_boxplot'],
   ['Quiver Plot', 'plot_special_quiver'],
   ['Violin Plot', 'plot_violin_basic'],
   // ["Mesh Plot", "plot_special_mesh"], // disabled due to webgl
   ['Graph Plot', 'plot_special_graph'],
   ['Sankey Plot', 'plot_special_sankey'],
+  ['Learning Curve', 'plot_line_learning_curve'],
   ['Matplotlib Plot', 'misc_plot_matplot'],
   ['Latex Plot', 'misc_plot_latex'],
   ['Video Pane', 'misc_video_tensor'],

example/components/plot_line.py

@@ -114,6 +114,33 @@ def plot_line_many_updates(viz, env, args):
         )
 
 
+def plot_line_learning_curve(viz, env, args):
+    epochs = np.arange(1, 11)
+    train_loss = np.exp(-epochs / 4.0) + 0.08 * np.random.rand(len(epochs))
+    val_loss = np.exp(-epochs / 3.7) + 0.12 * np.random.rand(len(epochs)) + 0.08
+    win = viz.learning_curve(
+        {
+            "train_loss": train_loss,
+            "val_loss": val_loss,
+        },
+        step=epochs,
+        opts={"title": "Learning curve", "ylabel": "loss"},
+        env=env,
+    )
+
+    for epoch in range(11, 16):
+        viz.learning_curve(
+            {
+                "train_loss": np.exp(-epoch / 4.0),
+                "val_loss": np.exp(-epoch / 3.7) + 0.08,
+            },
+            step=epoch,
+            win=win,
+            update="append",
+            env=env,
+        )
+
+
 def plot_line_opts(viz, env, args):
     return viz.line(
         X=np.column_stack(