diff --git a/doc/build-helpers/testers.chapter.md b/doc/build-helpers/testers.chapter.md
index b734cbbbd4e2..2e5e8ce7a26c 100644
--- a/doc/build-helpers/testers.chapter.md
+++ b/doc/build-helpers/testers.chapter.md
@@ -239,6 +239,12 @@ pkgs.testers.runNixOSTest ({ lib, ... }: {
 
 ## `nixosTest` {#tester-nixosTest}
 
+This function is deprecated in favor of [`runNixOSTest`](#tester-runNixOSTest). The reason why it's bad is that when you pass it a function, it is invoked via `callPackage`. This is somewhat incompatible with the module system and running cross-platform:
+  - The choice of packages is ambiguous when the VM host platform is not Linux. `nixosTest` could in theory pick either:
+    - `hostPkgs` for packages to run on the VM host
+    - or `config.node.pkgs` for packages that run in one of the VMs
+  - The return value of the passed function should have been a module, but `nixosTest` does not actually allow that.
+
 Run a NixOS VM network test using this evaluation of Nixpkgs.
 
 NOTE: This function is primarily for external use. NixOS itself uses `make-test-python.nix` directly. Packages defined in Nixpkgs [reuse NixOS tests via `nixosTests`, plural](#ssec-nixos-tests-linking).
diff --git a/pkgs/build-support/testers/default.nix b/pkgs/build-support/testers/default.nix
index 362622d9b7ee..c2eda4e716ed 100644
--- a/pkgs/build-support/testers/default.nix
+++ b/pkgs/build-support/testers/default.nix
@@ -118,6 +118,7 @@
        * make sense for this evaluation of Nixpkgs.
        */
       nixosTesting =
+        lib.warn "testers.nixosTest is deprecated. Use testers.runNixOSTest instead."
         (import ../../../nixos/lib/testing-python.nix {
           inherit (stdenv.hostPlatform) system;
           inherit pkgs;