Add cargoDocTest (#720)

---------

Co-authored-by: Ivan Petkov <[email protected]>

CHANGELOG.md

@@ -6,6 +6,11 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## Unreleased
 
+### Added
+
+* `cargoDocTest` is now available as an alternative to `cargoTest` which runs
+  only doc tests.
+
 ### Fixed
 * Vendoring dependencies avoids creating malformed TOML configurations in
   situations where registry name/url definitions cannot be found. When this

checks/default.nix

@@ -517,6 +517,13 @@ in
     };
   };
 
+  runCargoDocTests = myLib.cargoDocTest {
+    src = ./simple-only-tests;
+    cargoArtifacts = myLib.buildDepsOnly {
+      src = ./simple-only-tests;
+    };
+  };
+
   simple-nonflake = (import ../default.nix {
     inherit pkgs;
   }).buildPackage {

docs/API.md

@@ -507,6 +507,27 @@ environment variables during the build, you can bring them back via
 * `cargoDocExtraArgs`
 * `cargoExtraArgs`
 
+### `craneLib.cargoDocTest`
+
+`cargoDocTest :: set -> drv`
+
+Create a derivation which will run a `cargo test --doc` invocation in a cargo
+workspace. To run all or any tests for a workspace, consider `cargoTest`.
+
+Except where noted below, all derivation attributes are delegated to
+* `buildPhaseCargoCommand` will be set to run `cargo test --profile release` in
+  the workspace.
+  - `CARGO_PROFILE` can be set on the derivation to alter which cargo profile is
+    selected; setting it to `""` will omit specifying a profile altogether.
+* `pnameSuffix` will be set to `"-doctest"`
+
+#### Optional attributes
+* `cargoExtraArgs`: additional flags to be passed in the cargo invocation
+  - Default value: `"--locked"`
+* `cargoTestExtraArgs`: additional flags to be passed in the cargo
+  invocation
+  - Default value: `""`
+
 ### `craneLib.cargoFmt`
 
 `cargoFmt :: set -> drv`
@@ -629,7 +650,9 @@ environment variables during the build, you can bring them back via
 `cargoNextest :: set -> drv`
 
 Create a derivation which will run a `cargo nextest` invocation in a cargo
-workspace.
+workspace. Note that [`cargo nextest` doesn't run
+doctests](https://github.com/nextest-rs/nextest/issues/16), so you may also
+want to build a `cargoDocTest` derivation.
 
 Except where noted below, all derivation attributes are delegated to
 `mkCargoDerivation`, and can be used to influence its behavior.
@@ -748,7 +771,7 @@ Except where noted below, all derivation attributes are delegated to
 #### Optional attributes
 * `cargoExtraArgs`: additional flags to be passed in the cargo invocation
   - Default value: `"--locked"`
-* `cargoTestArgs`: additional flags to be passed in the cargo
+* `cargoTestExtraArgs`: additional flags to be passed in the cargo
   invocation
   - Default value: `""`
 
@@ -760,6 +783,14 @@ environment variables during the build, you can bring them back via
 * `cargoExtraArgs`
 * `cargoTestExtraArgs`
 
+#### Remove attributes
+The following attributes will be removed before being lowered to
+`mkCargoDerivation`. If you absolutely need these attributes present as
+environment variables during the build, you can bring them back via
+`.overrideAttrs`.
+* `cargoExtraArgs`
+* `cargoTestExtraArgs`
+
 ### `craneLib.cleanCargoSource`
 
 `cleanCargoSource :: path or drv -> drv`

lib/cargoDocTest.nix

@@ -0,0 +1,22 @@
+{ mkCargoDerivation
+}:
+
+{ cargoArtifacts
+, cargoExtraArgs ? "--locked"
+, cargoTestExtraArgs ? ""
+, ...
+}@origArgs:
+let
+  args = (builtins.removeAttrs origArgs [
+    "cargoExtraArgs"
+    "cargoTestExtraArgs"
+  ]);
+in
+mkCargoDerivation (args // {
+  inherit cargoArtifacts;
+  doCheck = args.doCheck or true;
+
+  pnameSuffix = "-doctest";
+  buildPhaseCargoCommand = "";
+  checkPhaseCargoCommand = "cargoWithProfile test --doc ${cargoExtraArgs} ${cargoTestExtraArgs}";
+})

lib/default.nix

@@ -59,6 +59,7 @@ let
       cargoClippy = callPackage ./cargoClippy.nix { };
       cargoDeny = callPackage ./cargoDeny.nix { };
       cargoDoc = callPackage ./cargoDoc.nix { };
+      cargoDocTest = callPackage ./cargoDocTest.nix { };
       cargoFmt = callPackage ./cargoFmt.nix { };
       cargoHelperFunctionsHook = callPackage ./setupHooks/cargoHelperFunctions.nix { };
       cargoLlvmCov = callPackage ./cargoLlvmCov.nix { };