Merge branch 'dev' into feat/migrate-export-to-playwright-v2

Author: Debajeet-1411

.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

@@ -287,6 +287,7 @@ The following API is currently supported:
 - [`vis.line`](#visline)     : line plots
 - [`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,6 +296,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
@@ -549,6 +552,34 @@ 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.stem
 This function draws a stem plot. It takes as input an `N` or `NxM` tensor
@@ -579,6 +610,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
@@ -879,7 +936,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.