diff --git a/docs/images/favicon.png b/docs/images/favicon.png deleted file mode 100755 index 4203f2a..0000000 Binary files a/docs/images/favicon.png and /dev/null differ diff --git a/docs/images/logo.png b/docs/images/logo.png deleted file mode 100755 index b8ff5f8..0000000 Binary files a/docs/images/logo.png and /dev/null differ diff --git a/docs/images/logo.svg b/docs/images/logo.svg new file mode 100755 index 0000000..93213ef --- /dev/null +++ b/docs/images/logo.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/options.md b/docs/options.md new file mode 100644 index 0000000..4ca74a4 --- /dev/null +++ b/docs/options.md @@ -0,0 +1,3 @@ +# Options + +{% include 'options.md' %} diff --git a/docs/style.css b/docs/style.css new file mode 100644 index 0000000..b2ae4ff --- /dev/null +++ b/docs/style.css @@ -0,0 +1,15 @@ +.md-header__button.md-logo { + margin: 0; + padding-top: .2rem; + padding-bottom: .2rem; +} + +[dir="ltr"] .md-header__title { + margin-left: 0; +} + +.md-header__button.md-logo img, +.md-header__button.md-logo svg { + height: 2rem; +} + diff --git a/flake.lock b/flake.lock index 09366e0..110c517 100644 --- a/flake.lock +++ b/flake.lock @@ -169,21 +169,6 @@ "type": "github" } }, - "mkdocs-material-umami": { - "locked": { - "lastModified": 1745840856, - "narHash": "sha256-1Ad1JTMQMP6YsoIKAA+SBCE15qWrYkGue9/lXOLnu9I=", - "owner": "technofab", - "repo": "mkdocs-material-umami", - "rev": "3ac9b194450f6b779c37b8d16fec640198e5cd0a", - "type": "gitlab" - }, - "original": { - "owner": "technofab", - "repo": "mkdocs-material-umami", - "type": "gitlab" - } - }, "nix": { "inputs": { "flake-compat": [ @@ -255,11 +240,11 @@ "nix-mkdocs": { "locked": { "dir": "lib", - "lastModified": 1745841841, - "narHash": "sha256-297zPQbUlc7ZAYDoaD6mCmQxCC3Tr4YOKekRF1ArZ7g=", + "lastModified": 1757055638, + "narHash": "sha256-KHYSkEreFe4meXzSdEbknC/HwaQSNClQkc8vzHlAsMM=", "owner": "technofab", "repo": "nixmkdocs", - "rev": "c7e3c3b13ded25818e9789938387bba6f2cde690", + "rev": "7840a5febdbeaf2da90babf6c94b3d0929d2bf74", "type": "gitlab" }, "original": { @@ -368,7 +353,6 @@ "inputs": { "devenv": "devenv", "flake-parts": "flake-parts_2", - "mkdocs-material-umami": "mkdocs-material-umami", "nix-devtools": "nix-devtools", "nix-gitlab-ci": "nix-gitlab-ci", "nix-mkdocs": "nix-mkdocs", diff --git a/flake.nix b/flake.nix index 9be0e25..72e77cc 100644 --- a/flake.nix +++ b/flake.nix @@ -17,6 +17,7 @@ perSystem = { lib, pkgs, + self', config, ... }: { @@ -65,81 +66,48 @@ }; }; - doc = { + docs."default".config = { path = ./docs; - deps = pp: [ - pp.mkdocs-material - (pp.callPackage inputs.mkdocs-material-umami {}) - ]; + material = { + enable = true; + colors = { + primary = "green"; + accent = "light green"; + }; + umami = { + enable = true; + src = "https://analytics.tf/umami"; + siteId = "716d1869-9342-4b62-a770-e15d2d5c807d"; + domains = ["nixtest.projects.tf"]; + }; + }; + macros = { + enable = true; + includeDir = toString self'.packages.optionsDocs; + }; config = { site_name = "Nixtest"; + site_url = "https://nixtest.projects.tf"; repo_name = "TECHNOFAB/nixtest"; repo_url = "https://gitlab.com/TECHNOFAB/nixtest"; - edit_uri = "edit/main/docs/"; + extra_css = ["style.css"]; theme = { - name = "material"; - features = ["content.code.copy" "content.action.edit"]; icon.repo = "simple/gitlab"; - logo = "images/logo.png"; - favicon = "images/favicon.png"; - palette = [ - { - scheme = "default"; - media = "(prefers-color-scheme: light)"; - primary = "green"; - accent = "light green"; - toggle = { - icon = "material/brightness-7"; - name = "Switch to dark mode"; - }; - } - { - scheme = "slate"; - media = "(prefers-color-scheme: dark)"; - primary = "green"; - accent = "light green"; - toggle = { - icon = "material/brightness-4"; - name = "Switch to light mode"; - }; - } - ]; + logo = "images/logo.svg"; + favicon = "images/logo.svg"; }; - plugins = ["search" "material-umami"]; nav = [ {"Introduction" = "index.md";} {"Usage" = "usage.md";} {"Reference" = "reference.md";} {"CLI" = "cli.md";} {"Example Configs" = "examples.md";} + {"Options" = "options.md";} ]; markdown_extensions = [ "pymdownx.superfences" "admonition" ]; - extra.analytics = { - provider = "umami"; - site_id = "716d1869-9342-4b62-a770-e15d2d5c807d"; - src = "https://analytics.tf/umami"; - domains = "nixtest.projects.tf"; - feedback = { - title = "Was this page helpful?"; - ratings = [ - { - icon = "material/thumb-up-outline"; - name = "This page is helpful"; - data = "good"; - note = "Thanks for your feedback!"; - } - { - icon = "material/thumb-down-outline"; - name = "This page could be improved"; - data = "bad"; - note = "Thanks for your feedback! Please leave feedback by creating an issue :)"; - } - ]; - }; - }; }; }; @@ -212,7 +180,8 @@ packages = let ntlib = import ./lib {inherit pkgs lib;}; - in { + doclib = inputs.nix-mkdocs.lib {inherit lib pkgs;}; + in rec { default = pkgs.callPackage ./package.nix {}; tests = ntlib.mkNixtest { modules = ntlib.autodiscover {dir = ./tests;}; @@ -220,6 +189,24 @@ inherit pkgs ntlib; }; }; + optionsDoc = doclib.mkOptionDocs { + module = { + _module.args.pkgs = pkgs; + imports = [ + ntlib.module + ]; + }; + roots = [ + { + url = "https://gitlab.com/TECHNOFAB/nixtest/-/blob/main/lib"; + path = toString ./lib; + } + ]; + }; + optionsDocs = pkgs.runCommand "options-docs" {} '' + mkdir -p $out + ln -s ${optionsDoc} $out/options.md + ''; }; }; }; @@ -235,7 +222,6 @@ nix-gitlab-ci.url = "gitlab:technofab/nix-gitlab-ci/2.0.1?dir=lib"; nix-devtools.url = "gitlab:technofab/nix-devtools?dir=lib"; nix-mkdocs.url = "gitlab:technofab/nixmkdocs?dir=lib"; - mkdocs-material-umami.url = "gitlab:technofab/mkdocs-material-umami"; }; nixConfig = { diff --git a/lib/module.nix b/lib/module.nix index 478584c..1600c50 100644 --- a/lib/module.nix +++ b/lib/module.nix @@ -13,6 +13,7 @@ removePrefix assertMsg generators + literalExpression ; nixtest-lib = import ./default.nix {inherit pkgs lib;}; @@ -27,6 +28,18 @@ _type = "unset"; }; isUnset = isType "unset"; + unsetOr = typ: + (types.either unsetType typ) + // { + inherit (typ) description getSubOptions; + }; + mkUnsetOption = opts: + mkOption (opts + // { + type = unsetOr opts.type; + default = opts.default or unset; + defaultText = literalExpression "unset"; + }); filterUnset = value: if builtins.isAttrs value && !builtins.hasAttr "_type" value @@ -45,8 +58,11 @@ ... }: { options = { - pos = mkOption { - type = types.either types.attrs unsetType; + pos = mkUnsetOption { + type = types.attrs; + description = '' + Position of test, use `__curPos` for automatic insertion of current position. + ''; default = pos; apply = val: if isUnset val @@ -57,6 +73,9 @@ }; type = mkOption { type = types.enum ["unit" "snapshot" "script"]; + description = '' + Type of test, has to be one of "unit", "snapshot" or "script". + ''; default = "unit"; apply = value: assert assertMsg (value != "script" || !isUnset config.script) @@ -76,43 +95,66 @@ }; name = mkOption { type = types.str; + description = '' + Name of this test. + ''; }; - description = mkOption { - type = types.either types.str unsetType; - default = unset; + description = mkUnsetOption { + type = types.str; + description = '' + Short description of the test. + ''; }; format = mkOption { type = types.enum ["json" "pretty"]; + description = '' + Which format to use for serializing arbitrary values. + Required since this config is serialized to JSON for passing it to Nixtest, so no Nix-values can be used directly. + + - `json`: serializes the data to json using `builtins.toJSON` + - `pretty`: serializes the data to a "pretty" format using `lib.generators.toPretty` + ''; default = "json"; }; - expected = mkOption { + expected = mkUnsetOption { type = types.anything; - default = unset; + description = '' + Expected value of the test. Remember, the values are serialized (see [here](#suitesnametestsformat)). + ''; apply = val: if isUnset val || config.format == "json" then val else generators.toPretty {} val; }; - actual = mkOption { + actual = mkUnsetOption { type = types.anything; - default = unset; + description = '' + Actual value of the test. Remember, the values are serialized (see [here](#suitesnametestsformat)). + ''; apply = val: if isUnset val || config.format == "json" then val else generators.toPretty {} val; }; - actualDrv = mkOption { - type = types.either types.package unsetType; - default = unset; + actualDrv = mkUnsetOption { + type = types.package; + description = '' + Actual value of the test, but as a derivation. + Nixtest will build this derivation when running the test, then compare the contents of the + resulting file to the [`expected`](#suitesnametestsexpected) value. + ''; apply = val: # keep unset value if isUnset val then val else builtins.unsafeDiscardStringContext (val.drvPath or ""); }; - script = mkOption { - type = types.either types.str unsetType; - default = unset; + script = mkUnsetOption { + type = types.str; + description = '' + Script to run for the test. + Nixtest will run this, failing the test if it exits with a non-zero exit code. + ''; apply = val: if isUnset val then val @@ -132,11 +174,19 @@ options = { name = mkOption { type = types.str; + description = '' + Name of the suite, uses attrset name by default. + ''; default = name; + defaultText = literalExpression name; }; - pos = mkOption { - type = types.either types.attrs unsetType; - default = unset; + pos = mkUnsetOption { + type = types.attrs; + description = '' + Position for tests, use `__curPos` for automatic insertion of current position. + This will set `pos` for every test of this suite, useful if the suite's tests are all in a single file. + ''; + example = literalExpression "__curPos"; }; tests = mkOption { type = types.listOf (types.submoduleWith { @@ -146,20 +196,30 @@ inherit testsBase; }; }); + description = '' + Define tests of this suite here. + ''; default = []; }; }; }; nixtestSubmodule = {config, ...}: { + _file = ./module.nix; options = { base = mkOption { - description = "Base directory of the tests, will be removed from the test file path"; type = types.str; + description = '' + Base directory of the tests, will be removed from the test file path. + This makes it possible to show the relative path from the git repo, instead of ugly Nix store paths. + ''; default = ""; }; skip = mkOption { type = types.str; + description = '' + Tests to skip, is passed to Nixtest's `--skip` param. + ''; default = ""; }; suites = mkOption { @@ -169,12 +229,22 @@ testsBase = config.base; }; }); + description = '' + Define your test suites here, every test belongs to a suite. + ''; default = {}; apply = suites: map ( n: filterUnset (builtins.removeAttrs suites.${n} ["pos"]) ) (builtins.attrNames suites); + example = { + "Suite A".tests = [ + { + name = "Some Test"; + } + ]; + }; }; finalConfigJson = mkOption { diff --git a/tests/lib_test.nix b/tests/lib_test.nix index 969e9a2..85a3c7a 100644 --- a/tests/lib_test.nix +++ b/tests/lib_test.nix @@ -72,6 +72,8 @@ '' ${ntlib.helpers.path [pkgs.gnugrep pkgs.mktemp pkgs.coreutils]} ${ntlib.helpers.scriptHelpers} + export SSL_CERT_FILE=${pkgs.cacert}/etc/ssl/certs/ca-bundle.crt + export NIX_SSL_CERT_FILE=${pkgs.cacert}/etc/ssl/certs/ca-bundle.crt cp -r ${./../snapshots} snapshots # start without nix & env binaries to expect errors