diff --git a/checks/default.nix b/checks/default.nix
index 7e198b6..b0b2e84 100644
--- a/checks/default.nix
+++ b/checks/default.nix
@@ -1,4 +1,7 @@
 {inputs, ...}: {
+  imports = [
+    ./testing.nix
+  ];
   perSystem = {
     pkgs,
     config,
diff --git a/checks/run-test.nix b/checks/run-test.nix
new file mode 100644
index 0000000..0db7ff3
--- /dev/null
+++ b/checks/run-test.nix
@@ -0,0 +1,69 @@
+{
+  writeShellApplication,
+  lib,
+  tests,
+  stdenv,
+  ...
+}:
+writeShellApplication {
+  name = "run-test";
+
+  runtimeInputs = [];
+
+  text = ''
+    cmd_name=$(basename "$0")
+
+    help() {
+      echo "  build and run a test"
+      echo
+      echo "  usage:"
+      echo "    $cmd_name <name>"
+      echo "    $cmd_name <name> --interactive"
+      echo "    $cmd_name -s <system> <name>"
+      echo
+      echo "  arguments:"
+      echo "    <name>"
+      echo
+      echo "  options:"
+      echo "    -h --help          show this screen."
+      echo "    -l --list          show available tests."
+      echo "    -s --system        specify the target platform [default: ${stdenv.system}]."
+      echo "    -i --interactive   run the test interactively."
+      echo
+    }
+
+    list() {
+      echo "  list of available tests:"
+      echo
+      echo "${lib.concatMapStrings (s: "    - " + s + "\n") (lib.mapAttrsToList (_: test: test.name) tests)}"
+    }
+
+    args=$(getopt -o lihs: --long list,interactive,help,system: -n 'tests' -- "$@")
+    eval set -- "$args"
+
+    system="${stdenv.system}"
+    driver_args=()
+
+    while [ $# -gt 0 ]; do
+    case "$1" in
+      -i | --interactive) driver_args+=("--interactive"); shift;;
+      -s | --system) system="$2"; shift 2;;
+      -h | --help) help; exit 0;;
+      -l | --list) list; exit 0;;
+      -- ) shift; break;;
+      * ) break;;
+      esac
+    done
+
+    if [ $# -eq 0 ]; then
+      help
+      exit 1
+    fi
+
+    name="$1"
+    shift
+
+    # build/run the test driver, passing any remaining arguments
+    nix run ".#checks.$system.testing-$name.driver" -- "''${driver_args[@]}"
+  '';
+}
diff --git a/checks/testing.nix b/checks/testing.nix
new file mode 100644
index 0000000..1efe54e
--- /dev/null
+++ b/checks/testing.nix
@@ -0,0 +1,102 @@
+{
+  lib,
+  inputs,
+  config,
+  ...
+}: let
+  inherit (lib) mkOption types mapAttrs' nameValuePair;
+  inherit (config.flake) nixosModules;
+in {
+  perSystem = {
+    config,
+    lib,
+    system,
+    pkgs,
+    ...
+  }: let
+    cfg = config.cardanoNix;
+  in {
+    options.cardanoNix = {
+      tests = mkOption {
+        type = types.lazyAttrsOf (types.submodule ({config, ...}: {
+          options = {
+            name = mkOption {
+              type = types.str;
+              default = config._module.args.name;
+              internal = true;
+            };
+            systems = mkOption {
+              type = types.listOf types.str;
+            };
+            module = mkOption {
+              type = types.deferredModule;
+            };
+            documentation = mkOption {
+              type = types.bool;
+              default = false;
+            };
+            specialArgs = mkOption {
+              type = types.attrsOf types.anything;
+              default = {};
+            };
+          };
+        }));
+      };
+      runTestScript = mkOption {
+        type = types.package;
+        default = pkgs.callPackage ./run-test.nix {inherit (cfg) tests;};
+        description = "A convenience script to run tests";
+      };
+      _nixosLib = mkOption {
+        type = types.anything;
+        default = import (inputs.nixpkgs.outPath + "/nixos/lib") {};
+        internal = true;
+      };
+      _mkCheckFromTest = mkOption {
+        type = types.functionTo types.package;
+        internal = true;
+        default = test:
+          (cfg._nixosLib.runTest {
+            hostPkgs = pkgs;
+
+            # false by default, it speeds up evaluation by skipping docs generation
+            defaults.documentation.enable = test.documentation;
+
+            node = {
+              inherit (test) specialArgs;
+            };
+
+            # import all of our flake nixos modules by default
+            defaults.imports = [
+              nixosModules.default
+            ];
+
+            # import the test module
+            imports = [test.module];
+          })
+          .config
+          .result;
+      };
+    };
+
+    config = {
+      checks =
+        mapAttrs'
+        (name: test: nameValuePair "testing-${test.name}" (cfg._mkCheckFromTest test))
+        (lib.filterAttrs
+          (_: v: lib.elem system v.systems)
+          cfg.tests);
+
+      apps.run-test.program = lib.getExe cfg.runTestScript;
+
+      devshells.default.commands = [
+        {
+          name = "run-test";
+          category = "testing";
+          help = "Run tests";
+          command = "${lib.getExe cfg.runTestScript} $@";
+        }
+      ];
+    };
+  };
+}
diff --git a/flake.nix b/flake.nix
index 05cb35c..9b1ef61 100644
--- a/flake.nix
+++ b/flake.nix
@@ -24,8 +24,8 @@
   outputs = inputs @ {flake-parts, ...}:
     flake-parts.lib.mkFlake {
       inherit inputs;
-    }
-    {
+    } {
+      debug = true;
       imports = [
         ./lib
         ./checks
@@ -33,6 +33,7 @@
         ./formatter
         ./modules
         ./shell
+        ./tests
       ];
       systems = [
         "x86_64-linux"
diff --git a/lib/default.nix b/lib/default.nix
index c8d977e..3c34976 100644
--- a/lib/default.nix
+++ b/lib/default.nix
@@ -1,5 +1,5 @@
 {lib, ...}: let
   lib' = import ./functions.nix lib;
 in {
-  flake.lib = lib';
+  config.flake.lib = lib';
 }
diff --git a/modules/default.nix b/modules/default.nix
index a70814e..8a7a7ef 100644
--- a/modules/default.nix
+++ b/modules/default.nix
@@ -1,4 +1,4 @@
-{
+{config, ...}: {
   imports = [
   ];
 
diff --git a/tests/cardano-cli.nix b/tests/cardano-cli.nix
new file mode 100644
index 0000000..4bc9dc1
--- /dev/null
+++ b/tests/cardano-cli.nix
@@ -0,0 +1,27 @@
+{
+  cardanoNix.tests = {
+    dummy = {
+      systems = ["x86_64-linux"];
+
+      module = {
+        name = "cli-test";
+
+        nodes = {
+          machine = {
+            virtualisation = {
+              cores = 2;
+              memorySize = 1024;
+              writableStore = true;
+            };
+            cardano-ecosystem.cli.enable = true;
+          };
+        };
+
+        testScript = ''
+          # FIXME: check for cardano cli, not git
+          machine.succeed("git --version")
+        '';
+      };
+    };
+  };
+}
diff --git a/tests/default.nix b/tests/default.nix
new file mode 100644
index 0000000..837ced2
--- /dev/null
+++ b/tests/default.nix
@@ -0,0 +1,7 @@
+{
+  perSystem = _: {
+    imports = [
+      ./cardano-cli.nix
+    ];
+  };
+}