From 808262314931f45b2f99db1151bacbb61de267ce Mon Sep 17 00:00:00 2001
From: Minijackson <minijackson@riseup.net>
Date: Tue, 30 Jul 2024 15:49:12 +0200
Subject: [PATCH 1/8] docs: make copybutton not copy console prompts and
 outputs

---
 docs/conf.py | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/conf.py b/docs/conf.py
index a56cfb77..852aff42 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -63,6 +63,12 @@
     },
 }
 
+# -- Options for Sphinx Copybutton -------------------------------------------
+# https://sphinx-copybutton.readthedocs.io/en/latest/use.html
+
+# Exclude copying line numbers, prompts, and prompt outputs
+copybutton_exclude = ".linenos, .gp, .go"
+
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 

From 02fee0687de7e219eb17463664dc96b5889105cc Mon Sep 17 00:00:00 2001
From: Minijackson <minijackson@riseup.net>
Date: Tue, 30 Jul 2024 15:50:06 +0200
Subject: [PATCH 2/8] templates/top: add timeout for first cagets

Because the test is added by default, and run by default in GitLab CI,
this means that by default the test will fail.

With this change, the test fails in 10 seconds instead of 15 minutes,
leaving more time for other jobs.
---
 templates/top/checks/simple.nix | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/templates/top/checks/simple.nix b/templates/top/checks/simple.nix
index 54a5948d..f511af04 100644
--- a/templates/top/checks/simple.nix
+++ b/templates/top/checks/simple.nix
@@ -22,8 +22,8 @@ pkgs.nixosTest {
     machine.wait_for_unit("default.target")
     machine.wait_for_unit("ioc.service")
 
-    machine.wait_until_succeeds("caget stringin")
-    machine.wait_until_succeeds("caget stringout")
+    machine.wait_until_succeeds("caget stringin", timeout=10)
+    machine.wait_until_succeeds("caget stringout", timeout=10)
     machine.fail("caget non-existing")
 
     with subtest("testing stringout"):

From ed5d02d39ca5ef191514aa0c6ff4e8601aa82445 Mon Sep 17 00:00:00 2001
From: Minijackson <minijackson@riseup.net>
Date: Tue, 30 Jul 2024 15:52:21 +0200
Subject: [PATCH 3/8] docs/ioc: adapt to default top template change

---
 docs/ioc/tutorials/streamdevice.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/ioc/tutorials/streamdevice.rst b/docs/ioc/tutorials/streamdevice.rst
index 528a7c9e..d1a679b4 100644
--- a/docs/ioc/tutorials/streamdevice.rst
+++ b/docs/ioc/tutorials/streamdevice.rst
@@ -85,7 +85,7 @@ change yours like so:
 
             # Add one of the supported modules here:
             # ---
-   -        #support.modules = with pkgs.epnix.support; [ StreamDevice ];
+   -        #support.modules = with pkgs.epnix.support; [ StreamDevice mySupportModule ];
    +        support.modules = with pkgs.epnix.support; [ StreamDevice ];
 
 Then,

From a5f45fa35bde9860cb102de2492a75650e77f503 Mon Sep 17 00:00:00 2001
From: Minijackson <minijackson@riseup.net>
Date: Tue, 30 Jul 2024 15:53:02 +0200
Subject: [PATCH 4/8] docs/ioc: adapt to simulator changes

The simulator was rewritten in Lewis, which changed its default port to
9999, and is now case-sensitive.
---
 docs/ioc/tutorials/streamdevice.rst | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/ioc/tutorials/streamdevice.rst b/docs/ioc/tutorials/streamdevice.rst
index d1a679b4..2fa2b38e 100644
--- a/docs/ioc/tutorials/streamdevice.rst
+++ b/docs/ioc/tutorials/streamdevice.rst
@@ -147,11 +147,11 @@ and what to expect in return.
    Terminator = LF;
 
    getVoltage {
-       out ":VOLT?"; in "%f";
+       out ":volt?"; in "%f";
    }
 
    setVoltage {
-       out ":VOLT %f";
+       out ":volt %f";
        @init { getVoltage; }
    }
 
@@ -207,7 +207,7 @@ and how to connect to the remote power supply.
    # Where to find the protocol files
    epicsEnvSet("STREAM_PROTOCOL_PATH", "${TOP}/db")
    # The TCP/IP address of the power supply
-   drvAsynIPPortConfigure("PS1", "localhost:8727")
+   drvAsynIPPortConfigure("PS1", "localhost:9999")
 
    ## Load record instances
    dbLoadRecords("${TOP}/db/example.db", "PREFIX=, PORT=PS1")
@@ -252,7 +252,7 @@ Then, run:
 
    ./st.cmd
 
-You should see the IOC starting and connecting to ``localhost:8727``.
+You should see the IOC starting and connecting to ``localhost:9999``.
 
 Recompiling with make
 ---------------------
@@ -274,9 +274,9 @@ and open a direct connection to the simulator:
 
 .. code-block:: bash
 
-   nc localhost 8727
+   nc localhost 9999
    # or
-   telnet localhost 8727
+   telnet localhost 9999
 
 You can install the ``nc`` command through the ``netcat`` package,
 or you can install the ``telnet`` command through the ``telnet`` package,

From a27299b57c303397adcaaa6eb0505a45bd63d294 Mon Sep 17 00:00:00 2001
From: Minijackson <minijackson@riseup.net>
Date: Tue, 30 Jul 2024 15:53:46 +0200
Subject: [PATCH 5/8] docs/ioc: add tip for bash prompt in a result symlink

---
 docs/ioc/tutorials/streamdevice.rst | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/docs/ioc/tutorials/streamdevice.rst b/docs/ioc/tutorials/streamdevice.rst
index 2fa2b38e..575084f9 100644
--- a/docs/ioc/tutorials/streamdevice.rst
+++ b/docs/ioc/tutorials/streamdevice.rst
@@ -254,6 +254,28 @@ Then, run:
 
 You should see the IOC starting and connecting to ``localhost:9999``.
 
+.. tip::
+   :file:`./result` is a symbolic link,
+   so if you made any changes to your IOC and re-ran ``nix build``,
+   a terminal window already in :file:`./result/iocBoot/iocExample` will still point to the old version.
+
+   To run the new version,
+   either re-open a new window
+   and ``cd`` into the new :file:`./result/`,
+   or in the old location,
+   you can run:
+
+   .. code-block:: console
+
+      user@machine .../result/iocBoot/iocExample $ cd .
+
+   For quickly re-running an IOC,
+   you can use this command:
+
+   .. code-block:: console
+
+      user@machine .../result/iocBoot/iocExample $ cd . ; ./st.cmd
+
 Recompiling with make
 ---------------------
 

From f7e96f106f3e764c4fd496b499665a57c68c061b Mon Sep 17 00:00:00 2001
From: Minijackson <minijackson@riseup.net>
Date: Tue, 30 Jul 2024 15:54:17 +0200
Subject: [PATCH 6/8] docs/ioc: update VOLT-RB value after VOLT is set

---
 docs/ioc/tutorials/streamdevice.rst | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/ioc/tutorials/streamdevice.rst b/docs/ioc/tutorials/streamdevice.rst
index 575084f9..0898d7f1 100644
--- a/docs/ioc/tutorials/streamdevice.rst
+++ b/docs/ioc/tutorials/streamdevice.rst
@@ -160,7 +160,7 @@ That file specifies the name, type, and properties of the Process Variables (PV)
 that EPICS exposes over the network.
 It also specifies how they relate to the functions written in the protocol file.
 
-.. code-block:: perl
+.. code-block:: bash
    :caption: :file:`exampleApp/Db/example.db`
 
    record(ai, "${PREFIX}VOLT-RB") {
@@ -171,6 +171,7 @@ It also specifies how they relate to the functions written in the protocol file.
    record(ao, "${PREFIX}VOLT") {
        field(DTYP, "stream")
        field(OUT, "@example.proto setVoltage ${PORT}")
+       field(FLNK, "${PREFIX}VOLT-RB")
    }
 
 Change ``exampleApp/Db/Makefile``

From b46224ce69fdbf2dfb8cbcbdcf01db7e692f34bd Mon Sep 17 00:00:00 2001
From: Minijackson <minijackson@riseup.net>
Date: Tue, 30 Jul 2024 15:55:28 +0200
Subject: [PATCH 7/8] docs/ioc: expand Integration tests tutorial

Renamed to "Adding integration tests to your IOC", because an
"Integration tests" user guide is planned, and to make it a bit clearer
that it is a continuation of the StreamDevice tutorial.

Previously the tutorial was a mix between a guide and tutorial, not
really guided enough.

Now the tutorial builds upon the StreamDevice tutorial, and shows a
complete path to have a fully functional integration test.

Also introduce how to *run* tests, both non-interactively and
interactively.

Added a quick reference of useful Python test functions.

The tutorial was also updated due to some changes in the default
template, and some renamed options.
---
 .../imgs/integration-vm-ioc-screenshot.png    | Bin 0 -> 10122 bytes
 .../integration-vm-simulator-screenshot.png   | Bin 0 -> 11700 bytes
 docs/ioc/tutorials/integration-tests.rst      | 488 +++++++++++++++---
 3 files changed, 412 insertions(+), 76 deletions(-)
 create mode 100644 docs/ioc/tutorials/imgs/integration-vm-ioc-screenshot.png
 create mode 100644 docs/ioc/tutorials/imgs/integration-vm-simulator-screenshot.png

diff --git a/docs/ioc/tutorials/imgs/integration-vm-ioc-screenshot.png b/docs/ioc/tutorials/imgs/integration-vm-ioc-screenshot.png
new file mode 100644
index 0000000000000000000000000000000000000000..a1948182cdc6a2e071f432d57ab89acafd998252
GIT binary patch
literal 10122
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
OC^;GBw-wUH!T$|TRcxvN

literal 0
HcmV?d00001

diff --git a/docs/ioc/tutorials/imgs/integration-vm-simulator-screenshot.png b/docs/ioc/tutorials/imgs/integration-vm-simulator-screenshot.png
new file mode 100644
index 0000000000000000000000000000000000000000..8e0ebcf93bf711925cb1c2b0f07242df0165b658
GIT binary patch
literal 11700
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
QKT%Ot(s){|VDa{U0YY`!ApigX

literal 0
HcmV?d00001

diff --git a/docs/ioc/tutorials/integration-tests.rst b/docs/ioc/tutorials/integration-tests.rst
index 77be658e..0377eaf5 100644
--- a/docs/ioc/tutorials/integration-tests.rst
+++ b/docs/ioc/tutorials/integration-tests.rst
@@ -1,37 +1,53 @@
-Integration tests
-=================
+Adding integration tests to your IOC
+====================================
+
+.. note::
+   This tutorial is a continuation of the :doc:`streamdevice` tutorial.
+
+   If you haven't already, follow the StreamDevice tutorial first.
+
+In this tutorial,
+you'll learn how to test your created StreamDevice IOC
+by running it against the simulator,
+inside a declared NixOS VM,
+and checking that it behaves as expected.
+
+This method of testing can then be automated
+by running it inside a Continuous Integration (CI) system.
 
 Writing the test
 ----------------
 
 Through the `NixOS testing framework`_,
 EPNix provides a way of specifying a machine configuration,
-and running a Python script that can do various kind of testing.
+and running a Python script that can do various kinds of testing.
 
-If you created your IOC using the EPNix template,
-like suggested in the :doc:`streamdevice` tutorial,
-you will see a ``checks/`` directory.
-This directory should contain the integration tests you want to run.
+With your IOC created during the :doc:`streamdevice` tutorial,
+you'll see a :file:`checks/` directory,
+which is the place to add your integration tests.
 
-To add an integration test to EPNix,
-record it in your ``flake.nix`` under the ``epnix.checks.files`` option.
+These tests are imported using the :ref:`opt-epnix.checks.imports` option.
 
-For example, in the EPNix template, you will see in your ``flake.nix`` file:
+For example,
+in the EPNix template,
+you'll see in your :file:`flake.nix` file:
 
 .. code-block:: nix
+   :caption: :file:`flake.nix`: importing an integration test
 
-   checks.files = [ ./checks/simple.nix ];
+   checks.imports = [ ./checks/simple.nix ];
 
-The ``./checks/<myTest>.nix`` file should contain a NixOS test like so:
+The :file:`./checks/simple.nix` file should contain a NixOS test such as this:
 
 .. code-block:: nix
+   :caption: :file:`checks/simple.nix`: structure of a test
 
    { build, pkgs, ... }:
 
    pkgs.nixosTest {
-     name = "myTest";
+     name = "simple";
 
-     machine = {
+     nodes.machine = {config, ...}: {
        # Description of the NixOS machine...
      };
 
@@ -40,102 +56,422 @@ The ``./checks/<myTest>.nix`` file should contain a NixOS test like so:
      '';
    }
 
-This test will create a NixOS virtual machine
+Running this test creates a NixOS virtual machine
 from the given configuration,
-and run the test script.
-Note that the test script does *not* run on the virtual machine,
-but communicates with it.
-This is because the test script can start,
+and runs the test script.
+
+The test script can,
+among other things,
+run commands on the machine,
+start,
 shut down,
-or reboot the machine,
-and also because NixOS tests can also manage several virtual machines,
-not just one.
+or reboot the machine.
+
+.. tip::
+   The Python test script does *not* run on the virtual machine,
+   but communicates with it.
+
+   If you want to run Python code on the VM machine,
+   you need to package it and run it as a command.
 
-For an overview of what you can input in the machine configuration,
-please refer to the `NixOS documentation`_.
-You can also read more about it
-in the `Python test script API documentation`_.
+For a more detailed overview of what you can put in the machine configuration,
+examine the `NixOS documentation`_,
+or the :doc:`../../nixos-services/tutorials/archiver-appliance` tutorial.
 
 .. _NixOS testing framework: https://nixos.org/manual/nixos/stable/index.html#sec-nixos-tests
 .. _NixOS documentation: https://nixos.org/manual/nixos/stable/index.html#sec-configuration-syntax
-.. _Python test script API documentation: https://nixos.org/manual/nixos/stable/index.html#sec-nixos-tests
 
 Starting your IOC through systemd
 ---------------------------------
 
-We recommend starting your IOC through a systemd service,
-which you can describe in Nix like so:
+First, you need to ensure that your IOC will start inside the VM.
+
+In the default template,
+you'll see this particular configuration:
+
+.. code-block:: nix
+   :caption: :file:`checks/simple.nix`: config for starting an IOC
+   :emphasize-lines: 3-4,8
+
+     nodes.machine = {config, ...}: {
+       imports = [
+         epnix.nixosModules.ioc
+         epnixConfig
+       ];
+       environment.systemPackages = [pkgs.epnix.epics-base];
+
+       systemd.services.ioc = config.epnix.nixos.services.ioc.config;
+     };
+
+The first two emphasized lines are about importing the ability to define an IOC,
+and then importing your IOC configuration
+that you defined in your :file:`flake.nix`.
 
-.. TODO: change that
+Then,
+on the last emphasized line,
+the systemd service configuration generated by EPNix is used
+to generate ``ioc.service``.
+
+EPNix uses the configuration :ref:`opt-epnix.nixos.services`
+from your :file:`flake.nix`
+to figure out the name of your app
+and the name of your :file:`iocBoot` folder.
+
+Make sure yours is correct in your :file:`flake.nix`:
 
 .. code-block:: nix
+   :caption: :file:`flake.nix`: configuring the name of your app
+     and iocBoot folder for the test systemd service
+   :emphasize-lines: 5-6
+
+           # Used when generating NixOS systemd services, for example for
+           # deployment to production, or for the NixOS tests in checks/
+           # ---
+           nixos.services.ioc = {
+             app = "example";    # Name of your app
+             ioc = "iocExample"; # Name of your iocBoot folder
+           };
+
+Also take note of the package :ref:`pkg-epics-base` being installed,
+with the ``environment.systemPackages`` option.
+This enables you to use the :command:`caget`, :command:`caput` commands
+inside the VM.
+
+.. _run-test:
+
+Running the test
+----------------
+
+To run the test,
+run this command:
+
+.. code-block:: bash
+   :caption: Running the test "simple"
+
+   nix build -L '.#checks.x86_64-linux.simple'
+
+If you left the test script as-is,
+you should see that the test fails.
+That's because the test script is currently not adapted to our IOC.
+
+We'll change it afterward,
+but for now in the logs you should see your IOC being run.
+
+If you have several tests,
+you can run them all using:
+
+.. code-block:: bash
+   :caption: Running all tests
+
+   nix flake check -L
+
+.. _run-driverInteractive:
+
+Running the test interactively
+------------------------------
+
+It's often desirable to run the VM interactively,
+to figure out what works and what doesn't,
+before writing the test.
 
-   # Inside the `machine` attribute
-   {
-     systemd.services.my-ioc = {
-       wantedBy = [ "multi-user.target" ];
-       serviceConfig = {
-         ExecStart = "${build}/iocBoot/iocexample/st.cmd";
-         WorkingDirectory = "${build}/iocBoot/iocexample";
-
-         # Makes the EPICS command-line not quit for 100 seconds, if it doesn't
-         # receive anything on the standard input
-         StandardInputText = "epicsThreadSleep(100)";
+To do so,
+run:
+
+.. code-block:: bash
+   :caption: Running the test "simple" interactively
+
+   nix run -L '.#checks.x86_64-linux.simple.driverInteractive'
+
+This runs a Python shell prompt in the same environment as the test script.
+Any command run here is the same as running it in the test script,
+but interactively.
+
+You can use the ``start_all()`` functions
+to start all VMs that you declared in ``nodes``:
+
+.. code-block:: pycon
+
+   >>> start_all()
+
+In our case,
+we only defined ``machine``,
+so this starts a single VM,
+and runs your IOC inside it.
+
+You can log in to that VM with the user ``root`` and no password.
+You can then run any command you want
+to inspect the state of the VM.
+
+.. figure:: ./imgs/integration-vm-ioc-screenshot.png
+   :alt: Integration VM screenshot showing the IOC running
+
+   Integration VM screenshot showing the IOC running
+
+.. tip::
+   If you have a non-English-language keyboard,
+   change your keyboard layout inside the VM by using :command:`loadkeys`.
+
+   For example,
+   to set the keyboard to "french":
+
+   .. code-block:: console
+
+      [root@machine:~]# loadkeys fr
+
+.. tip::
+   To exit the Python shell prompt,
+   press :kbd:`Ctrl-d`, then :kbd:`y`.
+
+   Exiting the Python shell prompt automatically shuts down the VMs.
+
+Adding the simulator
+--------------------
+
+The simulator is a program listening on port 9999.
+Inside the test VM,
+it should be a program run by a systemd service.
+
+Same as the IOC,
+you should use the ``systemd.services`` options.
+
+Change your Nix test file like this:
+
+.. code-block:: nix
+   :caption: Adding the simulator as systemd service,
+    important changes emphasized
+   :emphasize-lines: 1,10-13
+
+     nodes.machine = {config, lib, ...}: {
+       imports = [
+         epnix.nixosModules.ioc
+         epnixConfig
+       ];
+       environment.systemPackages = [pkgs.epnix.epics-base];
+
+       systemd.services = {
+         ioc = config.epnix.nixos.services.ioc.config;
+         simulator = {
+           serviceConfig.ExecStart = lib.getExe pkgs.epnix.psu-simulator;
+           wantedBy = ["multi-user.target"];
+         };
        };
      };
 
-     # Provides the caget / caput / etc. commands to the test script
-     environment.systemPackages = [ pkgs.epnix.epics-base ];
-   }
+The first emphasized line is about adding the ``lib`` argument used below.
+
+The second set of emphasized lines is about creating the ``simulator.service`` systemd service. These lines will generate the following service file:
+
+.. code-block:: dosini
+   :caption: generated :file:`/etc/systemd/system/simulator.service`
+
+   [Unit]
+
+   [Service]
+   # ...
+   ExecStart=/nix/store/...-psu-simulator/bin/psu-simulator
+
+And this service is automatically started at boot,
+by being a dependency of ``multi-user.target``.
 
-You can view the list of options available for a NixOS machine `here <https://search.nixos.org/options?channel=21.11&from=0&size=50&sort=alpha_asc&type=packages&query=systemd.services.>`__.
+The ``serviceConfig`` option adds configuration keys to the ``[Service]`` section.
+Here,
+we set ``ExecStart`` to main executable program of the ``psu-simulator`` package,
+by using the ``lib.getExe`` function.
 
-Then, you can write your test script.
-Note that the test script doesn’t run directly on the machine,
-but communicates with the machine through the ``machine`` variable.
+A ``unitConfig`` for the ``[Unit]`` section also exists.
 
-An example of a testing script:
+The ``[Install]`` section isn't present in NixOS,
+because managed differently,
+by using options such as ``wantedBy``, ``requiredBy``, etc.
+
+For more information,
+see the `systemd.services`_ options in the NixOS manual.
+
+.. _systemd.services: https://nixos.org/manual/nixos/stable/options#opt-systemd.services
+
+----
+
+With this configuration,
+you can run the VM interactively
+(see :ref:`run-driverInteractive`),
+and you should see the simulator up and running after booting.
+
+.. tip::
+   If you make changes to your configuration,
+   or your IOC,
+   you *don't* need to rebuild anything
+   before running the ``nix run`` command.
+
+   Nix will by itself figure out what it needs to rebuild,
+   and rebuild it before running the test.
+
+.. figure:: ./imgs/integration-vm-simulator-screenshot.png
+   :alt: Integration VM screenshot showing the simulator running
+
+   Integration VM screenshot showing the simulator running
+
+Writing the test
+----------------
+
+Now that the VM configuration is appropriate,
+you can start writing your test script.
+
+Here is a sample of useful Python functions:
+
+.. py:function:: start_all()
+
+   Start all defined VMs
+
+.. py:function:: Machine.wait_for_unit(self, unit: str, user: str | None = None, timeout: int = 900)
+
+   Wait for a systemd unit to get into “active” state.
+   Throws exceptions on “failed” and “inactive” states
+   as well as after timing out.
+
+   .. code-block:: python
+      :caption: Example
+
+      machine.wait_for_unit("ioc.service")
+
+.. py:function:: Machine.succeed(self, command: str, timeout: int | None = None)
+
+   Execute a shell command,
+   raising an exception if the exit status is not zero,
+   otherwise returning the standard output
+
+   .. code-block:: python
+      :caption: Example
+
+      machine.succeed("caput VOLT 42")
+
+.. py:function:: Machine.wait_until_succeeds(self, command: str, timeout: int = 900)
+
+   Repeat a shell command with 1-second intervals until it succeeds.
+
+   Be careful of the ``s`` in ``succeeds``.
+
+   .. code-block:: python
+      :caption: Example
+
+      machine.wait_until_succeeds("caget -t my:stringout | grep -qxF 'expected value'")
+
+.. py:function:: Machine.fail(self, command: str, timeout: int | None = None)
+
+   Like :py:func:`succeed`,
+   but raising an exception if the command returns a zero status.
+
+   .. code-block:: python
+      :caption: Example
+
+      machine.fail("caget unknown-PV")
+
+.. py:function:: Machine.wait_for_open_port(self, addr: int | str, timeout: int = 900)
+
+   Wait until a process is listening on the given TCP port and IP address (default ``localhost``).
+
+   .. code-block:: python
+      :caption: Example
+
+      machine.wait_for_open_port(9999)
+
+.. py:function:: retry(fn: Callable, timeout: int = 900)
+
+   Call the given function repeatedly, with 1-second intervals,
+   until it returns ``True`` or a timeout is reached.
+
+   .. code-block:: python
+      :caption: Example
+
+      def check_value(_last_call: bool) -> bool:
+          """Check whether the VOLT-RB PV is 42."""
+          value = float(machine.succeed("caget -t VOLT-RB"))
+          return value == 42.
+
+      retry(check_value, timeout=10)
+
+.. py:function:: subtest(name: str)
+
+   Group logs under a given test name.
+
+   To be used with the ``with`` syntax.
+
+   .. code-block:: python
+      :caption: Example
+
+      with subtest("check voltage"):
+          test_setting_voltage()
+          test_voltage_readback()
+          ...
+
+You can also read more about the Python functions available in the test script
+in the `NixOS tests documentation`_.
+
+.. _NixOS tests documentation: https://nixos.org/manual/nixos/stable/index.html#sec-nixos-tests
+
+Example test script
+^^^^^^^^^^^^^^^^^^^
+
+Here an example test script
+that should work with your StreamDevice IOC:
 
 .. code-block:: python
+   :caption: :file:`checks/simple.nix`: Example test script
 
    start_all()
 
-   machine.wait_for_unit("default.target")
-   machine.wait_for_unit("my-ioc.service")
+   with subtest("check services"):
+       machine.wait_for_unit("ioc.service")
+       machine.wait_for_unit("simulator.service")
+       machine.wait_for_unit("default.target")
 
-   machine.wait_until_succeeds("caget stringin")
-   machine.wait_until_succeeds("caget stringout")
-   machine.fail("caget non-existing")
+       machine.wait_for_open_port(9999)
 
-   with subtest("testing stringout"):
-       def test_stringout(_) -> bool:
-           machine.succeed("caput stringout 'hello'")
-           status, _output = machine.execute("caget -t stringout | grep -qxF 'hello'")
+   # Prefer using 'wait_until_succeeds',
+   # since the 'ioc.service' being active doesn't necessarily means
+   # that the IOC is initialized
+   machine.wait_until_succeeds("caget VOLT-RB", timeout=10)
+   machine.fail("caget unknown-PV")
 
-           return status == 0
+   with subtest("check voltage"):
+       # Initial value is zero
+       machine.succeed("caget -t VOLT-RB | grep -qxF '0'")
 
-       retry(test_stringout)
+       machine.succeed("caput VOLT 42")
 
-       assert "hello" not in machine.succeed("caget -t stringin")
+       def check_value(_last_call: bool) -> bool:
+           """Check whether the VOLT-RB PV is 42."""
+           value = float(machine.succeed("caget -t VOLT-RB"))
+           return value == 42.
 
-Note that the script extensively uses the ``wait_until_succeeds`` method and the ``retry`` function.
-This is because EPICS has few guarantees about whether it propagates changes immediately,
-and so it’s better to encourage the use of retries,
+       retry(check_value, timeout=10)
+
+Note that the script uses the ``wait_until_succeeds`` method and the ``retry`` function.
+This is because EPICS has few guarantees about whether it propagates changes immediately.
+It’s better to encourage the use of retries,
 instead of hoping the timing lines up.
 
-If you would like to use a fully fledged python script on the machine,
-which can use Python dependencies like pyepics,
-please refer to the guide :doc:`../user-guides/testing/packaging-python-scripts`.
+After changing your test script,
+run your test as explained in :ref:`run-test`.
 
-You can find methods available on the ``machine`` variable and other particularities in the `NixOS tests documentation`_.
+Next steps
+----------
 
-You can also look at examples either in the EPNix repository,
-under the `ioc/tests folder`_,
-or in nixpkgs under the `nixos/tests folder`_.
+You can examine other NixOS test examples:
 
-.. TODO: this doesn't explain how to run the test
+- In the `EPNix' ioc/tests`_ folder, for IOC tests,
+- In the `EPNix' nixos/tests`_ folder, for EPICS-related NixOS services tests,
+- Or in the `nixpkgs' nixos/tests`_ folder.
 
-.. _Packaging Python scripts: ../guides/testing/packaging-python-scripts.md
-.. _NixOS tests documentation: https://nixos.org/manual/nixos/stable/index.html#sec-nixos-tests
-.. _ioc/tests folder: https://github.com/epics-extensions/epnix/tree/master/ioc/tests
-.. _nixos/tests folder: https://github.com/NixOS/nixpkgs/tree/master/nixos/tests
+If you'd like to run a complete python script on the test VM,
+which can use Python dependencies such as ``pyepics``,
+examine the guide :doc:`../user-guides/testing/packaging-python-scripts`.
+
+If you're interested in adding unit tests,
+examine the :doc:`../user-guides/testing/unit-testing` guide.
+
+For all testing related guides,
+see :doc:`../user-guides/testing/index`.
+
+.. _EPNix' ioc/tests: https://github.com/epics-extensions/epnix/tree/master/ioc/tests
+.. _EPNix' nixos/tests: https://github.com/epics-extensions/epnix/tree/master/nixos/tests
+.. _nixpkgs' nixos/tests: https://github.com/NixOS/nixpkgs/tree/master/nixos/tests

From a0e3f8a4298ec376a79ea3c449eadaa85e4ab3e0 Mon Sep 17 00:00:00 2001
From: Minijackson <minijackson@riseup.net>
Date: Wed, 31 Jul 2024 15:46:13 +0200
Subject: [PATCH 8/8] docs/ioc: add section on KVM for integration test
 tutorial

Nix will show an error running tests if KVM is not present.
---
 docs/ioc/tutorials/integration-tests.rst | 44 ++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/docs/ioc/tutorials/integration-tests.rst b/docs/ioc/tutorials/integration-tests.rst
index 0377eaf5..7ef2fbf4 100644
--- a/docs/ioc/tutorials/integration-tests.rst
+++ b/docs/ioc/tutorials/integration-tests.rst
@@ -15,6 +15,50 @@ and checking that it behaves as expected.
 This method of testing can then be automated
 by running it inside a Continuous Integration (CI) system.
 
+Pre-requisites
+--------------
+
+.. warning::
+   Nix assumes you can run hardware-accelerated VMs,
+   through KVM.
+
+Make sure that you have KVM on your Linux machine
+by checking if the file :file:`/dev/kvm` is present.
+
+If the file is present,
+you can proceed to the next section.
+
+If you don't have KVM,
+and you're running Nix on a physical machine,
+examine your firmware settings
+to see if you can enable hardware-accelerated virtualization.
+The setting can show up as:
+
+- Virtualization
+- Intel Virtualization Technology
+- Intel VT
+- VT-d
+- SVM Mode
+- AMD-v
+
+If you don't have KVM,
+and you're running Nix on a virtual machine,
+check your firmware settings
+as said before,
+and look up your hypervisor documentation
+to enable nested virtualization.
+
+If this doesn't work,
+you can still proceed without hardware acceleration
+by adding this line to your :file:`nix.conf`:
+
+.. code-block::
+   :caption: :file:`/etc/nix/nix.conf`
+
+   extra-system-features = kvm
+
+Note that this means much slower integration tests.
+
 Writing the test
 ----------------