tests/completion: document the "three" completion tests

There are "three" completion tests that multiply with the large number of
variatns present in the suite. The "simple" test is unsual and I don't fully
understand how it works because it does not install the test-snapd-complexion
snap at all. Instead it relies on running the completion script directly,
without the snap complete/etelpmoc script pair working across the sandbox.

Signed-off-by: Zygmunt Krynicki <[email protected]>

tests/completion/indirect/task.yaml

@@ -1,5 +1,27 @@
 summary: indirect completion
 
+details: |
+  Snapd contains a special system for tab-completion of snap applications, where
+  the bulk of the completion logic runs under confinement, and communicates with
+  a trusted, unconfined helper provided by snapd.
+
+  Like all the other completion tests, this test relies on a set of files
+  $variant.{complete,sh,vars} where foo $variant is one of the many variants of
+  the tests/complete suite: plain, plain_plusdirs, funky, files, hosts,
+  hosts_n_dirs, func, funkyfunc, funcarg. In each case the .vars file adds
+  environment variables needed by the test, the .sh script is executed during
+  test setup and the .complete script replaces the bash completer in the
+  test-snapd-complexion snap.
+
+  Like all the other completion tests this test is mostly implemented with
+  expect(1) to interact with bash, send and receive snippets of text.
+
+  This test installs the snap test-snapd-complexion and uses expect(1) to check
+  the intended behavior, while running as the test user. This test relies on the
+  complete.sh/etelpmoc.sh pair of scripts to communicate across the barrier
+  created by the snap execution sandbox. This test checks how the completion
+  system interacts with snap aliases.
+
 prepare: |
   (
       cd ../../lib/snaps/test-snapd-complexion || exit 1

tests/completion/simple/task.yaml

@@ -1,5 +1,24 @@
 summary: simple completion
 
+details: |
+  Snapd contains a special system for tab-completion of snap applications, where
+  the bulk of the completion logic runs under confinement, and communicates with
+  a trusted, unconfined helper provided by snapd.
+
+  Like all the other completion tests, this test relies on a set of files
+  $variant.{complete,sh,vars} where foo $variant is one of the many variants of
+  the tests/complete suite: plain, plain_plusdirs, funky, files, hosts,
+  hosts_n_dirs, func, funkyfunc, funcarg. In each case the .vars file adds
+  environment variables needed by the test, the .sh script is executed during
+  test setup and the .complete script replaces the bash completer in the
+  test-snapd-complexion snap.
+
+  Like all the other completion tests this test is mostly implemented with
+  expect(1) to interact with bash, send and receive snippets of text.
+
+  This test relies bypasses the complete.sh/etelpmoc.sh pair of scripts and does
+  not communicate across the barrier created by the snap execution sandbox.
+
 execute: |
   d="$PWD"
   #shellcheck disable=SC1090

tests/completion/snippets/task.yaml

@@ -1,4 +1,25 @@
-summary: indirect completion
+summary: snippets completion?
+
+details: |
+  Snapd contains a special system for tab-completion of snap applications, where
+  the bulk of the completion logic runs under confinement, and communicates with
+  a trusted, unconfined helper provided by snapd.
+
+  Like all the other completion tests, this test relies on a set of files
+  $variant.{complete,sh,vars} where foo $variant is one of the many variants of
+  the tests/complete suite: plain, plain_plusdirs, funky, files, hosts,
+  hosts_n_dirs, func, funkyfunc, funcarg. In each case the .vars file adds
+  environment variables needed by the test, the .sh script is executed during
+  test setup and the .complete script replaces the bash completer in the
+  test-snapd-complexion snap.
+
+  Like all the other completion tests this test is mostly implemented with
+  expect(1) to interact with bash, send and receive snippets of text.
+
+  This test installs the snap test-snapd-complexion and uses expect(1) to check
+  the intended behavior, while running as the test user. This test relies on the
+  complete.sh/etelpmoc.sh pair of scripts to communicate across the barrier
+  created by the snap execution sandbox.
 
 prepare: |
   (