Commit 20fccd7b authored by Robert Hensing's avatar Robert Hensing Committed by github-actions[bot]
Browse files

testers.lycheeLinkCheck: Update docs 

A deep dive reveals that the needles in our haystack are actually
regular expressions.

(cherry picked from commit 076c5afd209e76c4da9d379115e95ef0550d5741)
parent 25a5fced

doc/build-helpers/testers.chapter.md

+11 −8
Original line number Diff line number Diff line
@@ -67,9 +67,9 @@ This tester produces a package that does not produce useful outputs, but only su 


It has two modes:



- Use the returned package directly, and the build process will check that internal hyperlinks are correct. This runs in the sandbox, so it will not check external hyperlinks, but it is quick and reliable.

- Build the returned derivation; its build process will check that internal hyperlinks are correct. This runs in the sandbox, so it will not check external hyperlinks, but it is quick and reliable.



- Invoke the `.online` attribute with [`nix run`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-run) ([experimental](https://nixos.org/manual/nix/stable/contributing/experimental-features#xp-feature-nix-command)). This runs outside the sandbox, and check that both internal and external hyperlinks are correct.

- Invoke the `.online` attribute with [`nix run`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-run) ([experimental](https://nixos.org/manual/nix/stable/contributing/experimental-features#xp-feature-nix-command)). This runs outside the sandbox, and checks that both internal and external hyperlinks are correct.

  Example:



  ```shell
@@ -84,16 +84,19 @@ It has two modes: 


`remap` (attribe set, optional) {#tester-lycheeLinkCheck-param-remap}



: An attribute set where the attribute names are the URLs to remap.

: An attribute set where the attribute names are regular expressions.

  The values should be strings, derivations or path values.



  The values should be store path strings, derivations or path values.

  In the returned check's default configuration, external URLs are only checked when you run the `.online` attribute.



  Before checking the existence of URLs, if it is equal to the attribute name, it is replaced by the value of the attribute.

  If it is a subpath of the attribute name, it is replaced by a subpath of the value.

  By adding remappings, you can check offline that URLs to external resources are correct, by providing a file system based stand-in.



  This is useful for remapping URLs that are not accessible from the build environment.

  Before checking the existence of a URL, the regular expressions are matched and replaced by their corresponding values.



  Example: `{ "https://blog.example.com" = site; }`

  Example: `{ "https://blog\\.example\\.com" = site; }`



  Store path in the attribute values are automatically prefixed with `file://`, because lychee requires this for paths in the file system.

  If this is a problem, or if you need to control the order in which replacements are performed, use `extraConfig.remap` instead.



`extraConfig` (attribute set) {#tester-lycheeLinkCheck-param-extraConfig}

pkgs/build-support/testers/lychee.nix

+3 −2
Original line number Diff line number Diff line 
deps@{ formats, lib, lychee, stdenv, writeShellApplication }:

let

  inherit (lib) concatLists isPath mapAttrsToList;

  inherit (lib) isPath mapAttrsToList;

  inherit (lib.strings) hasPrefix;



  toURL = v:

    if builtins.isString v && hasPrefix builtins.storeDir v

      || isPath v

    then "file://${v}"

    then # lychee requires that paths on the file system are prefixed with file://

      "file://${v}"

    else "${v}";



  # See https://nixos.org/manual/nixpkgs/unstable/#tester-lycheeLinkCheck

pkgs/tools/networking/lychee/tests/fail.nix

+1 −1
Original line number Diff line number Diff line
@@ -9,7 +9,7 @@ let 


  linkCheck = testers.lycheeLinkCheck rec {

    site = sitePkg + "/dist";

    remap = { "https://example.com"= site; };

    remap = { "https://exampl[e]\\.com" = site; };

  };



  failure = testers.testBuildFailure linkCheck;

pkgs/tools/networking/lychee/tests/ok.nix

+1 −1
Original line number Diff line number Diff line
@@ -3,7 +3,7 @@ let 
  sitePkg = runCommand "site" { } ''

    dist=$out/dist

    mkdir -p $dist

    echo "<html><body><a href=\"https://example.com/foo.html\">foo</a></body></html>" > $dist/index.html

    echo "<html><body><a href=\"https://example.com/foo.html\">foo</a><a href=\"https://nixos.org/this-is-ignored.html\">bar</a></body></html>" > $dist/index.html

    echo "<html><body><a href=\".\">index</a></body></html>" > $dist/foo.html

  '';

in testers.lycheeLinkCheck rec {