diff --git a/doc/manual/rl-next/pytest-suite.md b/doc/manual/rl-next/pytest-suite.md
new file mode 100644
index 000000000..f4dbda1e8
--- /dev/null
+++ b/doc/manual/rl-next/pytest-suite.md
@@ -0,0 +1,10 @@
+---
+synopsis: "The beginnings of a new pytest-based functional test suite"
+category: Development
+cls: [2036, 2037]
+credits: jade
+---
+
+The existing integration/functional test suite is based on a large volume of shell scripts.
+This often makes it somewhat challenging to debug at the best of times.
+The goal of the pytest test suite is to make tests have more obvious dependencies on files and to make tests more concise and easier to write, as well as making new testing methods like snapshot testing easy.
diff --git a/package.nix b/package.nix
index b0b933ece..2d485be93 100644
--- a/package.nix
+++ b/package.nix
@@ -245,6 +245,7 @@ stdenv.mkDerivation (finalAttrs: {
     [
       python3
       python3.pkgs.pytest
+      python3.pkgs.pytest-xdist
       meson
       ninja
       cmake
@@ -479,6 +480,7 @@ stdenv.mkDerivation (finalAttrs: {
             # FIXME: these have to be added twice due to the nix shell using a
             # wrapped python instead of build inputs for its python inputs
             p.pytest
+            p.pytest-xdist
 
             p.yapf
             p.python-frontmatter
diff --git a/tests/functional2/README.md b/tests/functional2/README.md
index 8d8aa244b..b0440fb3a 100644
--- a/tests/functional2/README.md
+++ b/tests/functional2/README.md
@@ -18,7 +18,7 @@ Its primary goal is to make tests more concise, more self-contained, easier to w
 - [ ] Web server fixture: we don't test our network functionality because background processes are hard and this is simply goofy.
   We could just test it.
 - [ ] Nix daemon fixture.
-- [ ] Parallelism via pytest-xdist.
+- [x] Parallelism via pytest-xdist.
 
 [pytest-expect-test]: https://pypi.org/project/pytest-expect-test/
 [pytest-insta]: https://pypi.org/project/pytest-insta/
diff --git a/tests/functional2/meson.build b/tests/functional2/meson.build
index 590f11dd9..b18d7035d 100644
--- a/tests/functional2/meson.build
+++ b/tests/functional2/meson.build
@@ -1,3 +1,10 @@
+xdist_opts = [
+  # auto number of workers, max 12 jobs
+  '-n', 'auto', '--maxprocesses=12',
+  # group tests by module or class; ensures that any setup work occurs as little as possible
+  '--dist=loadscope',
+]
+
 # surprisingly, this actually works even if PATH is set to something before
 # meson gets hold of it. neat!
 functional2_env = environment()
@@ -7,7 +14,10 @@ test(
   'functional2',
   python,
   args : [
-    '-m', 'pytest', meson.current_source_dir()
+    '-m', 'pytest',
+    '-v',
+    xdist_opts,
+    meson.current_source_dir()
   ],
   env : functional2_env,
   # FIXME: Although we can trivially use TAP here with pytest-tap, due to a meson bug, it is unusable.