From 1c379b18dc518dee5be1fc829110843357cc28ee Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 14 Oct 2026 04:47:28 +0000 Subject: [PATCH 1/2] Docs: rewrite the human test protocol for the alpha test set; one install page; true apps, hosts and pins - HUMAN_TEST_PROTOCOL.md rewritten: test-set record sheet (Tools tag, template, host tags, app releases, links, OS, tester, date), install rules (no space in the path, Linux -u only after a finished install, tagged installs, latest only), discovery matrix as the rule to be, W1 as a refusal test, QuPath as a host, Fiji jar/script zip and its limits, Napari with PyQt6. - Per-app case files in docs/human_tests/ (NucleiSky, Playground, GuessTheCondition, VLab4Mic, CellTracksColab); CellTracksColab is no longer expected in any host and its bridge fixtures are gone. - New docs/INSTALL.md (apps and the three hosts); linked from README and the protocol. - TESTING.md, REPOSITORIES.md, OPERATIONS.md (pin table), HOST_FEATURES.md, README.md updated; CellTracksColab link fixed. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01Y2SN8SuEakTdiWy3F2WUqN --- README.md | 13 +- docs/HOST_FEATURES.md | 18 +- docs/HUMAN_TEST_PROTOCOL.md | 663 ++++++++--------------- docs/INSTALL.md | 50 ++ docs/OPERATIONS.md | 39 +- docs/REPOSITORIES.md | 34 +- docs/TESTING.md | 28 +- docs/TESTING_PROMPT.md | 2 +- docs/human_tests/celltrackscolab.md | 30 + docs/human_tests/guessthecondition.md | 64 +++ docs/human_tests/nucleisky.md | 226 ++++++++ docs/human_tests/playground.md | 99 ++++ docs/human_tests/vlab4mic.md | 58 ++ docs/img/F9_fiji_table_result.png | Bin 182359 -> 0 bytes docs/img/N14_napari_table_celltracks.png | Bin 237634 -> 0 bytes 15 files changed, 849 insertions(+), 475 deletions(-) create mode 100644 docs/INSTALL.md create mode 100644 docs/human_tests/celltrackscolab.md create mode 100644 docs/human_tests/guessthecondition.md create mode 100644 docs/human_tests/nucleisky.md create mode 100644 docs/human_tests/playground.md create mode 100644 docs/human_tests/vlab4mic.md delete mode 100644 docs/img/F9_fiji_table_result.png delete mode 100644 docs/img/N14_napari_table_celltracks.png diff --git a/README.md b/README.md index 5add630..f2c0b0a 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,7 @@ The toolkit is currently installed from GitHub, from the tag of the current pre- python -m pip install https://github.com/CellMigrationLab/LabConstrictor-Tools/archive/refs/tags/v0.3.0-alpha.1.zip ``` -The applications you want to use must be installed and registered separately. Their installers normally handle registration. +The applications you want to use must be installed and registered separately. Their installers normally handle registration. How to install an app and each host (Napari, Fiji, QuPath) is on one page: [docs/INSTALL.md](docs/INSTALL.md). ```bash labconstrictor-tools list @@ -86,17 +86,18 @@ The `check` command validates declarations; `test` runs declared tools with samp The bridge lists tools registered by installed applications. The following repositories provide applications or test tools; they are not bundled with this toolkit. - [Playground](https://github.com/CellMigrationLab/LabConstrictor-Playground) ([releases](https://github.com/CellMigrationLab/LabConstrictor-Playground/releases)): synthetic images, example outputs and installation diagnostics. -- [Guess the Condition](https://github.com/CellMigrationLab/GuessTheCondition) ([releases](https://github.com/CellMigrationLab/GuessTheCondition/releases), [Colab](https://colab.research.google.com/github/CellMigrationLab/GuessTheCondition/blob/main/notebooks/GuessTheCondition/GuessTheCondition.ipynb)): blinded classification of microscopy images across biological repeats. Its code declares six tools: five game actions and a helper that supplies condition choices. The application documents Napari, Fiji and CLI use. -- [VLab4Mic desktop](https://github.com/CellMigrationLab/LabConstrictor-VLab4Mic) ([releases](https://github.com/CellMigrationLab/LabConstrictor-VLab4Mic/releases)): fluorescence image simulation; the application documents Napari and Fiji use. -- [NucleiSky](https://github.com/CellMigrationLab/NucleiSky) ([releases](https://github.com/CellMigrationLab/NucleiSky/releases)): image registration from nuclei landmarks. The Fiji bridge includes NucleiSky integration tests. -- [CellTracksColab desktop](https://github.com/CellMigrationLab/CellTracksColab_LabConstrictor) ([releases](https://github.com/CellMigrationLab/CellTracksColab_LabConstrictor/releases)): tracking-data analysis. Check which tools are available in the installed version. +- [Guess the Condition](https://github.com/CellMigrationLab/GuessTheCondition) ([releases](https://github.com/CellMigrationLab/GuessTheCondition/releases), [Colab](https://colab.research.google.com/github/CellMigrationLab/GuessTheCondition/blob/main/notebooks/GuessTheCondition/GuessTheCondition.ipynb)): blinded classification of microscopy images across biological repeats. Its code declares six tools: five game actions and a helper that supplies condition choices. Offered by Napari, Fiji and QuPath. +- [VLab4Mic desktop](https://github.com/CellMigrationLab/LabConstrictor-VLab4Mic) ([releases](https://github.com/CellMigrationLab/LabConstrictor-VLab4Mic/releases)): fluorescence image simulation. Offered by Napari and Fiji, not by QuPath. +- [NucleiSky](https://github.com/CellMigrationLab/NucleiSky) ([releases](https://github.com/CellMigrationLab/NucleiSky/releases)): image registration from nuclei landmarks. Offered by Napari, Fiji and QuPath. +- [CellTracksColab](https://github.com/CellMigrationLab/CellTracksColab) ([releases](https://github.com/CellMigrationLab/CellTracksColab/releases)): tracking-data analysis in notebooks (desktop app released from this repository). A notebook app: no host offers it. (This list used to link `CellTracksColab_LabConstrictor`, which was not reachable when checked on 14 Oct 2026: not verified that it exists.) -**These are examples, not an allowlist.** The same registered tool manifest is available to each host that supports its protocol version. The practical question is whether the tool's inputs and outputs make sense in that host: a slide-region analysis may suit QuPath, an image-registration tool may suit Fiji, and a layer-based analysis may suit Napari. Host-specific presentation differs; check [host features](docs/HOST_FEATURES.md) when it matters. Run `labconstrictor-tools list` to inspect your installed tools. +**Which host offers which app is a rule** ([REPOSITORIES.md](docs/REPOSITORIES.md#what-is-shared): CellTracksColab is notebook only; VLab4Mic is not offered by QuPath; the rule is being implemented). For the tools of an app that a host does offer, the same registered tool manifest is available to each host that supports its protocol version. The practical question is whether the tool's inputs and outputs make sense in that host: a slide-region analysis may suit QuPath, an image-registration tool may suit Fiji, and a layer-based analysis may suit Napari. Host-specific presentation differs; check [host features](docs/HOST_FEATURES.md) when it matters. Run `labconstrictor-tools list` to inspect your installed tools. ## Documentation - [Authoring tools](docs/AUTHORING.md) — declarations, registration, notebook integration, tests - [Manifest reference](docs/MANIFEST.md) — types, input relationships and interface hints +- [Install an app and the hosts](docs/INSTALL.md) — one page: installers, Napari, Fiji, QuPath, the install rules - [Host features](docs/HOST_FEATURES.md) — what Fiji, Napari and QuPath do with those declarations - [Operations](docs/OPERATIONS.md) — registration, shared installs, diagnostics, logs and security boundaries - [Protocol](docs/PROTOCOL.md) — schema, data formats and worker messages diff --git a/docs/HOST_FEATURES.md b/docs/HOST_FEATURES.md index e0063c9..2325faf 100644 --- a/docs/HOST_FEATURES.md +++ b/docs/HOST_FEATURES.md @@ -2,6 +2,22 @@ Hosts: **Napari** (dock widget), **Fiji** (SciJava dialog, Groovy script or jar), **QuPath** (JavaFX window). "plain" = shown as an ordinary field, nothing is lost. +## Installing and requirements per host +All three need an app whose Tools is **0.3.0a1 or newer**; how to install each host is on one page, [INSTALL.md](INSTALL.md). + +| | Napari | Fiji | QuPath | +|---|---|---|---| +| What you install | `pip install` of the Tools tag and the plugin tag into napari's Python 3.11+ environment; **Qt6 backend** (`napari[pyqt6]` or `napari[pyside6]`; PyQt5 is not tested) | the jar from the release into `Fiji.app/plugins/`; alternative: the script zip (script **and `lib`**) | the jar from the release (drag onto QuPath, QuPath **0.7.0**); alternative for the Script Editor: the **single** `LabConstrictorTools-all.groovy` (the repository's part files do not run there) | +| Menu entry | Plugins > LabConstrictor tools | Plugins > LabConstrictor > LabConstrictor Tools... (jar) / ... Tools (script) | Extensions > LabConstrictor tools... | +| Tested by | CI on Linux, Windows, macOS with PySide6 and PyQt6 | GUI cases on Linux in CI; Windows and macOS (arm64) only best effort in the release run | GUI cases on Linux in CI; Windows and macOS (arm64) informative in the release run | +| Releases | no tag or release when this was written | no release when this was written (the workflow publishes jar, script zip and `SHA256SUMS` when the maintainer publishes one) | no release when this was written (jar, single script and `SHA256SUMS`) | + +**Fiji limits (known, stated in the Fiji README):** a pixel-size field linked to an image follows that image's calibration by itself and there is **no "use the image's calibration" button**; typing the value the box already shows cannot be detected in a SciJava dialog (conformance case CAL-T9), so that field is cleared and the run blocked with a message, never a wrong value sent; `EnabledWhen` is ignored; `Collapsed` is a plain heading; no kept worker (a new worker for each run); the Macro Recorder does not record the plugin (a hand-typed macro line works, jar only). + +## Which apps a host offers +Each host reads the registry. Which app each host *must* offer is the discovery rule (decided 14 Oct 2026; implemented in Tools by a pull request on the branch `claude/app-hosts-discovery`): **CellTracksColab** is hidden from Napari, Fiji and QuPath (notebook only); **NucleiSky, Guess the Condition and Playground** are offered by all three; **VLab4Mic** is offered by Napari and Fiji and **not** by QuPath. discovery rule: see PROTOCOL.md section . Until that rule is in a Tools tag a host offers every registered app that passes its compatibility check (not verified for each host). A host also leaves out, with a sentence in its Log, an app whose Tools is too old. The test steps are in [HUMAN_TEST_PROTOCOL.md](HUMAN_TEST_PROTOCOL.md#6-discovery-who-shows-which-app). + + | Feature | Napari | Fiji | QuPath | |---|---|---|---| | Plain parameters, bounds, units, tooltips | yes | yes | yes | @@ -11,7 +27,7 @@ Hosts: **Napari** (dock widget), **Fiji** (SciJava dialog, Groovy script or jar) | `Widget("slider")` / `Widget("radio")` | `FloatSlider`, `Slider`, radio buttons | slider and radio styles | slider beside the box, radio buttons | | `Copy as command` (host feature, no manifest change) | button with a menu: terminal line or Python snippet | the Log after each run; menu entry "Copy last run as command" | menu button: terminal line or Python snippet | | `EnabledWhen` | greys out | ignored: every field stays editable | greys out | -| `PixelSizeOf` | prefilled from the layer's scale and length unit; a bare scale with pixel units is *not calibrated* (blank, run blocked) | prefilled from the calibration; uncalibrated: blank, run blocked | prefilled from the image; uncalibrated: blank, run blocked | +| `PixelSizeOf` | prefilled from the layer's scale and length unit; a bare scale with pixel units is *not calibrated* (blank, run blocked) | prefilled from the calibration; uncalibrated: blank, run blocked; no "use the image's calibration" button, and typing the value the box shows clears it (CAL-T9, see above) | prefilled from the image; uncalibrated: blank, run blocked | | `ChoicesFrom` (dropdown) | yes, updates when its inputs change | yes, from the previous run's values; text field the first time | yes, updates when its inputs change | | `ClearAfterRun` | yes | not needed (a fresh dialog every run) | yes | | `Replace` | updates the layer or dock in place | closes the previous window, overlay or ROIs | reuses the results window, replaces the annotation | diff --git a/docs/HUMAN_TEST_PROTOCOL.md b/docs/HUMAN_TEST_PROTOCOL.md index 688369a..ae83024 100644 --- a/docs/HUMAN_TEST_PROTOCOL.md +++ b/docs/HUMAN_TEST_PROTOCOL.md @@ -1,27 +1,46 @@ -# Human test protocol: LabConstrictor tools in Napari and Fiji +# Human test protocol: LabConstrictor apps in Napari, Fiji and QuPath -**Purpose.** Check, by hand and on a real computer, that a LabConstrictor app (NucleiSky and CellTracksColab are used here) installs, -registers its tools, and that those tools work in **Napari** and in **Fiji**, and fail in an understandable way when something is wrong. +**Purpose.** Check, by hand and on a real computer, that the LabConstrictor apps install, register their tools, show up in the hosts that +are meant to show them (and in no other), run there, and fail in an understandable way when something is wrong. -**Who.** Anyone who can install a program and use Napari/Fiji. No programming is needed; a few steps type one command into a terminal. +**Who.** Anyone who can install a program and use Napari, Fiji or QuPath. No programming is needed; a few steps type one command into a terminal. -**How long.** About 2 hours for everything, 30 minutes for the *Quick path*. Run it once per operating system (Windows, macOS, Linux). +**How long.** The *Quick path* below is about 45 minutes per operating system. Everything is several hours: do the parts you were asked for. -**What this protocol replaces.** `docs/TESTING_PROMPT.md` is a prompt for an AI agent that tests from source; this file is the one for people. +**What this replaces.** `docs/TESTING_PROMPT.md` is a prompt for an AI agent that tests from source; this file is the one for people. +The automated counterpart is the release sandbox ([TESTING.md](TESTING.md#release-sandbox-a-released-app-on-fresh-runners)): it tests a +released app on fresh runners, but only Napari for most apps and Fiji/QuPath only for the Playground, and no human look at a screen. + +**How to install** the apps and the hosts: [INSTALL.md](INSTALL.md) (the one install page; section 2 and N0/F0/Q0 below repeat what a tester needs and are the test steps). + +## How this protocol is split + +| File | Content | +|---|---| +| this file | the **test-set record sheet**, the install rules, the discovery matrix, set-up of the hosts, tests that do not depend on an app (install, listing, errors, uninstall), the report | +| [human_tests/nucleisky.md](human_tests/nucleisky.md) | NucleiSky in Napari, Fiji and QuPath (the long case set: values you can check) | +| [human_tests/playground.md](human_tests/playground.md) | Playground: the diagnostic readout and every bridge feature in the three hosts | +| [human_tests/guessthecondition.md](human_tests/guessthecondition.md) | Guess the Condition (a game played tool by tool) in the three hosts | +| [human_tests/vlab4mic.md](human_tests/vlab4mic.md) | VLab4Mic in Napari and Fiji (and its absence from QuPath) | +| [human_tests/celltrackscolab.md](human_tests/celltrackscolab.md) | CellTracksColab: a notebook app, which no host shows | ## How to use this document -1. Copy this file (or paste it into a new GitHub issue: the boxes then become clickable). Print it if you prefer paper. -2. Fill in the **Record sheet** (section 0). -3. Do the sections in order. Each test has **Do** (what to do), **Expect** (what you should see) and three boxes. Tick exactly one: - * `PASS` : what you see matches **Expect**. - * `FAIL` : it differs. Write what you saw in *Notes*, and take a screenshot. - * `N/A` : you could not do the step (say why in *Notes*; "no Windows machine" is a valid reason). +1. Copy this file and the case file of each app you test (or paste them into a GitHub issue: the boxes then become clickable). Print them if you prefer paper. +2. Fill in the **Record sheet** (section 0). **Every result is tied to the versions in it**: a result without a filled record sheet cannot be used. +3. Do the sections in order. Each test has **Do**, **Expect** and three boxes. Tick exactly one: + * `PASS`: what you see matches **Expect**. + * `FAIL`: it differs. Write what you saw in *Notes*, and take a screenshot. + * `N/A`: you could not do the step (say why; "no Windows machine" is a valid reason). 4. Do not skip a failing test: note it and continue, unless the test says **STOP**. -5. At the end, send the record sheet, the screenshots and a support bundle (section 10). +5. At the end, send the record sheet, the screenshots and a support bundle (section 9). + +**Statements marked "not verified"** are things the authors of this protocol could not check themselves. If you see something different, that is a finding: write it down, it is not a mistake of yours. -**Quick path (30 minutes, after the installers have run).** Section 2 (test data), S1, S2, S3, N0, N1, N3, N4, N6, F0, F1, F3, F5, U1, U2. Everything else is the full protocol. +**Quick path.** S1 to S4, D1 to D3, N0/F0/Q0 for the hosts you were asked to test, then in each app file the first three tests of each host +(listing, one normal run, one error). Everything else is the full protocol. **Severity** (use it when you write a FAIL): + | Level | Meaning | |---|---| | Blocker | cannot install, cannot start, data lost, or a wrong scientific result **without any warning** | @@ -29,50 +48,69 @@ registers its tools, and that those tools work in **Napari** and in **Fiji**, an | Minor | works, but confusing, slow, or a wrong label | | Cosmetic | spelling, alignment | -**Words used.** *App* = a LabConstrictor installer program (NucleiSky, CellTracksColab). *Tool* = one function of an app that appears -in Napari/Fiji (NucleiSky: "Relocalize 2D"; CellTracksColab: "Calculate Track Metrics"). *Registry* = the folder where installed apps -announce themselves. *Prefix* = the folder you chose when installing the app. +**Words used.** *App* = a LabConstrictor installer program. *Tool* = one function of an app that appears in a host. *Host* = Napari, Fiji or +QuPath. *Registry* = the folder where installed apps announce themselves. *Prefix* = the folder you chose when installing the app. +*Test set* = the exact versions of everything in the record sheet. --- -## 0. Record sheet (fill in before you start) +## 0. Record sheet: the test set (fill in before you start) + +### 0.1 The test set (the maintainer fills this in before the round; testers copy it) +Testers install **only this set** and only the **latest** of each item: an older release or a branch is not a test of this round. If a +row below still says ``, the set is not ready: do not start. (Why exact versions: an installed app carries the Tools it was built +with; hosts refuse an app whose Tools is too old; a result is meaningless without knowing which pieces met.) + +| Item | Value | Download link (exact) | +|---|---|---| +| Tools tag | `v0.3.0-alpha.1` (Python version `0.3.0a1`); commit `` | https://github.com/CellMigrationLab/LabConstrictor-Tools/releases/tag/v0.3.0-alpha.1 (the tag is created by the maintainer: until it exists the apps cannot install) | +| Template version of the apps | `` (apps are on 0.1.17 today; 0.1.18 is a template pull request that is not merged: not verified which one the releases below carry; read `.template_sync/manifest.yaml` of the release tag) | n/a | +| Napari plugin tag | `` (the plugin had no tag when this was written) | `https://github.com/CellMigrationLab/LabConstrictor-napari/archive/refs/tags/.zip` | +| Fiji plugin tag | ``; file `labconstrictor-fiji-.jar` (and `labconstrictor-fiji-script-.zip`, `SHA256SUMS`) | `https://github.com/CellMigrationLab/LabConstrictor-Fiji/releases` (no release existed when this was written: not verified) | +| QuPath plugin tag | ``; file `labconstrictor-qupath-.jar` (and `LabConstrictorTools-all.groovy`, `SHA256SUMS`) | `https://github.com/CellMigrationLab/LabConstrictor-QuPath/releases` (no release existed when this was written: not verified) | +| Napari / Fiji / QuPath themselves | Napari `` (Python 3.11 or newer); Fiji `` (Java build: ask); QuPath **0.7.0** (the plugin is built against it, other versions are not supported) | https://napari.org, https://fiji.sc, https://qupath.github.io | +| NucleiSky | planned **0.1.4** (pin pull request #38); `` | https://github.com/CellMigrationLab/NucleiSky/releases | +| Playground | planned **0.0.4** (pin pull request #27); `` | https://github.com/CellMigrationLab/LabConstrictor-Playground/releases | +| VLab4Mic | planned **0.1.6** (pin pull request #17); `` | https://github.com/CellMigrationLab/LabConstrictor-VLab4Mic/releases | +| Guess the Condition | planned **0.0.1** (pin pull request #14; the app is at 0.0.0 today); `` | https://github.com/CellMigrationLab/GuessTheCondition/releases | +| CellTracksColab | latest release (1.1.1 when this was written; no new release is planned before the bridge decision); notebook app only | https://github.com/CellMigrationLab/CellTracksColab/releases | +| Installer file names (per app, per OS) | `` | | + +The "planned" numbers are the next free release numbers of each app after its pin pull request: the table must be corrected to what was +really published. The pins in the apps are `v0.2.0-rc.1` today and become `v0.3.0-alpha.1` only after the pin pull requests are merged and the apps +are released ([OPERATIONS.md](OPERATIONS.md#pinning-tools-in-app-installers)); an app release that still pins `v0.2.0-rc.1` is **not** part of this +test set (Fiji and QuPath leave it out of their lists, Napari refuses it: that is correct behaviour, see D4). + +### 0.2 The tester and the computer | Field | Your entry | |---|---| | Tester name and date | | | Operating system and version (e.g. Windows 11 23H2, macOS 14.5 Apple silicon (Intel Macs are not supported), Ubuntu 24.04) | | -| Computer: RAM, is it a managed/office computer with antivirus or admin restrictions? | | -| Are you behind a proxy or firewall? | | -| Do you have admin rights? (Yes / No) | | -| Napari version and how it was installed | | -| Fiji version (Help > About ImageJ) | | -| NucleiSky installer file name | | -| CellTracksColab installer file name | | +| RAM; a managed/office computer with antivirus or admin restrictions? Behind a proxy or firewall? Admin rights? | | +| Does your user name or the folder you will install into contain a space? (see S0) | | +| Napari: version, Python version, Qt backend (`pip list`), how it was installed | | +| Fiji: version (Help > About ImageJ), jar or script install | | +| QuPath: version (Help > About), jar or script install | | | Was LabConstrictor installed on this computer before? (existing apps, existing `.labconstrictor` folder) | | -| Prefix (install folder) of NucleiSky / CellTracksColab | | +| Prefix (install folder) of each app you installed | | --- ## 1. What you need -- [ ] A computer with the operating system you will report on (Windows, Linux, or a Mac with Apple silicon: **Intel Macs are not supported**, the installers cannot install there because some required packages no longer ship Intel Mac builds; if you only have an Intel Mac, please tell us instead of testing), and at least 25 GB of free disk space (NucleiSky downloads PyTorch: its installed folder is about 9 GB, the download caches take about 5 GB more, and the optional Cellpose model 1.2 GB). On a very bare Linux system Napari may also need the `libxcb-*` system packages (error `Could not load the Qt platform plugin "xcb"`): install them with your package manager; that is a computer setup problem, not a LabConstrictor one. -- [ ] Internet access during installation (the installers download packages) and, for item N9, for the first Cellpose/InstanSeg run. -- [ ] The two installers for your operating system (from the project's release page or from the person who sent you this protocol): NucleiSky and CellTracksColab. -- [ ] Python 3.10 or newer to create the Napari environment (or an existing Napari installation you are allowed to modify; a fresh one is better). -- [ ] Fiji (https://fiji.sc, "Fiji with Java"). Use a fresh unzipped copy, not your daily one, if you can. +- [ ] A computer with the operating system you will report on: Windows, Linux, or a Mac with Apple silicon. **Intel Macs are not supported** (some required packages no longer ship Intel Mac builds; if you only have an Intel Mac, tell us instead of testing; four app repositories still build an Intel installer, which is not a promise that it works: not verified). At least 25 GB of free disk space for NucleiSky and Playground (PyTorch: about 9 GB installed, about 5 GB of download caches). +- [ ] Internet access during installation (the installers download packages) and for the tests that say so. +- [ ] The installers of the apps in the record sheet for your system, from the exact links there. +- [ ] For the hosts you test: Napari in a Python 3.11+ environment you may modify (a fresh one is better); Fiji ("Fiji with Java"), a fresh unzipped copy if you can; QuPath 0.7.0. - [ ] A screenshot tool, a text editor, and this document. -**Folder names used below.** Replace `` and `` with the install folders of NucleiSky and CellTracksColab -(type the real folder: nothing in `<...>` is a variable your terminal understands). - **Which Python.** Each app has its own Python. The commands below start it by its full path: | | Linux / macOS (terminal) | Windows (PowerShell) | |---|---|---| -| NucleiSky's Python (``) | `/bin/python` | `& "\python.exe"` | -| CellTracksColab's Python (``) | `/bin/python` | `& "\python.exe"` | +| `` of the app installed in `` | `/bin/python` | `& "\python.exe"` | -In every command, `` / `` stands for the matching line of this table, typed in full (in PowerShell the `&` and the quotes are -needed, also when the path has no space). Unless a test says otherwise, use **NucleiSky's** Python for `list`, `doctor` and `support-bundle`. -Windows users: if your terminal is `cmd.exe` instead of PowerShell, leave out the `&`. +In every command `` stands for that line, typed in full (in PowerShell the `&` and the quotes are needed; in `cmd.exe` leave out the `&`). +Nothing in `<...>` is a variable your terminal understands: type the real folder. **Where things are** | What | Linux / macOS | Windows | @@ -85,527 +123,282 @@ Windows users: if your terminal is `cmd.exe` instead of PowerShell, leave out th --- -## 2. Test data (5 minutes) -You need three small files. They are generated with the Python that comes with the installed NucleiSky (it already has everything needed). +## 2. Install rules (read before S1) +1. **No space anywhere in the install path.** The installers refuse a destination folder that contains a space (the installer builder's + default `check_path_spaces`, kept on purpose). If your Windows user name contains a space, the installer's default folder contains one too + and is refused: choose a folder such as `C:\LabConstrictor\` (Windows) or `~/labconstrictor/` (macOS, Linux). Test W1 checks the refusal. +2. **Updating.** macOS and Windows: uninstall the old version first, then install the new one (the installer does not install over an existing install). + Linux: `bash .sh -u -p ` updates in place **only if the previous install finished**; after a failed or interrupted install delete + `/pkgs` (or uninstall and install again), otherwise the update breaks. (Source: OPERATIONS and TESTING pages of this repository, from the + sandbox findings of 13 Oct; the template's own install page for this is in an unmerged pull request, template #33.) +3. **Tagged installs only.** Install exactly the tagged things in the record sheet. Never `main.zip`, never a branch archive, never + `pip install` of Tools from `main`. The apps install Tools from a pinned tag (`LC_TOOLS_PIN` in their `post_install` hooks); the Napari line below pins the Tools tag + and the plugin tag. +4. **Only the latest.** Do not test an older release "to compare". If you already have an older app, uninstall it first (rule 2), or say so in the record sheet. -**Do, Linux/macOS (terminal):** -``` -mkdir testdata -cd testdata -curl -L -O https://raw.githubusercontent.com/CellMigrationLab/NucleiSky/bridge-test/lc_tests/make_fixtures.py -/bin/python make_fixtures.py ns -curl -L -o tracks.csv https://raw.githubusercontent.com/CellMigrationLab/CellTracksColab/bridge-test/lc_tests/fixtures/tracks.csv -echo hello > fake.tif -``` -**Do, Windows (PowerShell; type `curl.exe`, not `curl`, which PowerShell redirects to something else):** -``` -mkdir testdata -cd testdata -curl.exe -L -O https://raw.githubusercontent.com/CellMigrationLab/NucleiSky/bridge-test/lc_tests/make_fixtures.py -& "\python.exe" make_fixtures.py ns -curl.exe -L -o tracks.csv https://raw.githubusercontent.com/CellMigrationLab/CellTracksColab/bridge-test/lc_tests/fixtures/tracks.csv -"hello" | Out-File -Encoding ascii fake.tif -``` -`fake.tif` is a text file that pretends to be an image (used to check the error messages). Cutting a real image short is optional (test E3). +--- -**Write down the full path of this `testdata` folder** (in the terminal: `pwd` on Linux/macOS, `Get-Location` in PowerShell). From here on, -**`` means that exact folder**, for example `/home/anna/testdata` or `C:\Users\Anna\testdata`; `testdata/ns/reference.tif` means `/ns/reference.tif`. +## 3. Which host shows which app (the discovery matrix) +This is the **decided rule**; it is enforced by a rule in the Tools repository that is being implemented (branch `claude/app-hosts-discovery`) and is not +in the code you test until that pull request is merged and part of the test set (not verified: check the Tools tag of your set). +Today, without it, every host lists every registered app that passes its compatibility check ([REPOSITORIES.md](REPOSITORIES.md)); the tests D1 to D3 are written for the rule. +discovery rule: see PROTOCOL.md section -**Expect:** the folder `ns` contains `reference.tif` (5.1 MB), `query.tif` (0.5 MB), `reference_mask.tif`, `query_mask.tif`, `ground_truth.json`, plus a few more masks used only by the project's own automated tests (`*_binary.tif`, `*_fractions.tif`: ignore them); the last line printed by the generator is `ok (1600, 1600) (520, 520)`. +| App | Napari | Fiji | QuPath | Notebook (the app's own window) | +|---|---|---|---|---| +| NucleiSky | listed | listed | listed | yes | +| Guess the Condition | listed | listed | listed | yes | +| Playground | listed | listed | listed | yes | +| VLab4Mic | listed | listed | **not listed** | yes | +| CellTracksColab | **hidden** | **hidden** | **hidden** | yes (notebook only) | -- [ ] PASS - [ ] FAIL - [ ] N/A Notes: ______________________________ +"Hidden" and "not listed" mean the same for you: the app is not in the application drop-down, and nothing is broken. The release sandbox +tests CellTracksColab as "must be hidden" (it registers a tool there on purpose, so that hiding is what is tested); on the installer you test +it may register no tool at all, which hides it trivially. --- -## 3. Installation and registration - -### S1. Install NucleiSky -**Do:** run the NucleiSky installer. Choose an install folder (write it in the record sheet). Wait until it says it has finished. -(Linux batch example: `bash NucleiSky-0.1.1-Linux-x86_64.sh -b -p `. macOS: use the macOS installer file you were given, for example `bash -b -p `; never the Linux file.) This takes several minutes (it downloads PyTorch). +## 4. Install and registration -**Expect:** the installer finishes without an error message and without asking to close it manually after a failure. -The file `/menuinst_debug.log` exists and its last line is `Post-install completed successfully.` +### S0. The path +**Do:** choose, for each app, a prefix without a space (rule 1) and write it in the record sheet. Windows: do not use the default folder if your user name has a space. - [ ] PASS - [ ] FAIL - [ ] N/A Notes: ______________________________ -### S2. The tools were registered during installation -**Do:** open `menuinst_debug.log` of NucleiSky and search for `lc_tools`. (During installation the installer downloads the small *labconstrictor-tools* package from GitHub, so the computer needs internet access at that moment; the log shows `Successfully installed labconstrictor-tools-...`.) -* Linux/macOS: expect the lines `Found nucleisky_lc_tools: registering the tools of NucleiSky for Napari and Fiji` and - `Tools registered (labconstrictor-tools list shows them).` There must be **no** line starting with `WARNING: tool registration failed`. -* Windows: expect the line `Found nucleisky_lc_tools: registering ...`, followed by a block of text that contains `"schema_path"`, - and **no** line starting with `WARNING: tool registration failed`. (The Windows script does not print "Tools registered".) - -Then run, with NucleiSky's Python (see "Which Python"): -* Linux/macOS: `/bin/python -m labconstrictor_tools list` -* Windows PowerShell: `& "\python.exe" -m labconstrictor_tools list` +### S1. Install an app +**Do:** run the installer of the app you test (Linux batch example: `bash NucleiSky--Linux-x86_64.sh -b -p `; use the file of +your system, never the Linux file on a Mac). This takes several minutes (6 to 8 for a small app; PyTorch apps longer): the window may look idle. -**Expect:** the output contains `NucleiSky (0.1.1)` followed by an indented line `relocalize Relocalize 2D`. +**Expect:** the installer finishes without an error message. `/menuinst_debug.log` exists and its last line is `Post-install completed successfully.` - [ ] PASS - [ ] FAIL - [ ] N/A Notes: ______________________________ -### S3. Install CellTracksColab -**Do:** run the CellTracksColab installer (same as S1, install folder ``). Then run `list` with CellTracksColab's Python: -* Linux/macOS: `/bin/python -m labconstrictor_tools list` -* Windows PowerShell: `& "\python.exe" -m labconstrictor_tools list` +### S2. The tools were registered during installation +**Do:** open `menuinst_debug.log`, search for `lc_tools`. (The installer downloads the small *labconstrictor-tools* package from GitHub, so it needs internet at that moment: the log shows +`Successfully installed labconstrictor-tools-...`; the version must be `0.3.0a1`.) Then run ` -m labconstrictor_tools list`. +* Linux/macOS: expect `Found _lc_tools: registering the tools of ...` and `Tools registered (labconstrictor-tools list shows them).` +* Windows: expect `Found _lc_tools: registering ...` followed by a block of text containing `"schema_path"`. (The Windows script does not print "Tools registered".) +* Neither: no line starting with `WARNING: tool registration failed`. -**Expect:** the installer finishes; its `menuinst_debug.log` shows the same registration lines as in S2 (module `celltracks_lc_tools`). -`list` shows **both** apps: `CellTracksColab (1.1.0)` with `calculate_metrics Calculate Track Metrics`, and `NucleiSky (0.1.1)`. +**Expect:** `list` shows the app at the release version with its tools (the case file of the app names them). **CellTracksColab:** no such lines and no entry in `list` is expected (see its case file). - [ ] PASS - [ ] FAIL - [ ] N/A Notes: ______________________________ -### S4. Diagnose -**Do:** -* Linux/macOS: `/bin/python -m labconstrictor_tools doctor` -* Windows PowerShell: `& "\python.exe" -m labconstrictor_tools doctor` +### S3. Diagnose +**Do:** ` -m labconstrictor_tools doctor`. -**Expect:** one line per app starting with a check mark, e.g. `NucleiSky 1 tool(s), schema current, interpreter /bin/python (0.05 s)`; no line starting with a cross. -The last lines name the registry folder and the log file location. +**Expect:** one line per registered app starting with a check mark, no line starting with a cross; the last lines name the registry folder and the log file. - [ ] PASS - [ ] FAIL - [ ] N/A Notes: ______________________________ -### S5. Nothing unexpected was installed or written +### S4. Nothing unexpected was installed or written **Do:** look in your home folder. -**Expect:** the only new **LabConstrictor** folder is `.labconstrictor` (registry, logs, runs). The installer itself may also create menu entries (on Linux under `~/.local/share/applications`, which also gets `fiji.desktop` when Fiji first starts, and `~/.local/share/desktop-directories`) and the folders of the tools it uses (`~/.conda`, `~/.mamba`, `~/.cache`, `~/.config`, `~/.local/share/mime`; later also `~/.imagej` and `~/.java` from Fiji and `~/.cellpose` from Cellpose), including dated backups of `~/.config/menus/applications.menu`: that is normal and not a failure. No error dialogs appeared during installation. Installation did not require administrator rights unless you chose a protected folder. - -- [ ] PASS - [ ] FAIL - [ ] N/A Notes: ______________________________ - ---- - -## 4. Command line (optional, 10 minutes) -### C1. Run a tool without any window -**Do:** -* Linux/macOS: `/bin/python -m labconstrictor_tools run CellTracksColab calculate_metrics tracks=/tracks.csv` -* Windows PowerShell: `& "\python.exe" -m labconstrictor_tools run CellTracksColab calculate_metrics tracks=\tracks.csv` - -**Expect:** a JSON report with `"status": "COMPLETE"`, a result of type `table`, and a last line `(results are in ...results/