Engine/Testing p≡p Sync

Prerequisites

  1. p≡p Sync can be tested using p≡p Python adapter.
  2. If the tests should show color then termcolor must be installed.

Tests

The tests can be found in pEpPythonAdapter/test. There are two test programs.

High-level test: sync_test.py

~ $ cd pEpPythonAdapter/test
test $ python3 sync_test.py --help
Usage: sync_test.py [options]

test runner for sync tests  Start this with:  $ python3 sync_test.py

Options:
  -h, --help            show this help message and exit
  -c, --clean           remove all generated files
  -b, --backup          make a backup of all generated files (old backup will
                        be overwritten)
  -r, --restore         restore generated files from backup
  -C, --clean-all       remove all generated files including backup files
  -s, --setup           setup environment, then stop
  -p, --print           print sync message trace in inbox
  -E NOTIFICATIONS, --end-on=NOTIFICATIONS
                        end test on these notifications
  -3, --third-device    start Pad as third device
  -j, --multi-threaded  use multithreaded instead of single threaded
                        implementation

The high level test by default is executing two processes, which simulate two devices (red: phone, green: laptop) with a single threaded implementation of p≡p Sync each. Those devices are executing a Sync handshake by default. The full message flow is being shown, which is sent by the two devices.

Usage:

test $ python3 sync_test.py

If p≡p engine is compiled without NDEBUG then it will output debug messages. These are the messages lead by three asterisks (***) and having no color, i.e.:

*** remaining in state KeySync Grouped service KeySync_fsm.c:1523

All other messages are from the tests. When sending a XER version of the message is being printed in the color of the sending device, i.e.:

<!-- sending from Phone -->
<Sync>
    <keysync>
        <ownKeysRequester>
            <ownIdentities>
                <Identity>
                    <address>alice@peptest.ch</address>
                    <fpr>AB3D3A2F30EAB04BD69ACBA06019180C900624FC</fpr>
                    <user-id>Phone</user-id>
                    <username>Laptop of Alice Neuman</username>
                    <comm-type>255</comm-type>
                    <lang>en</lang>
                </Identity>
            </ownIdentities>
        </ownKeysRequester>
    </keysync>
</Sync>

When receiving a message the <keysync> part of the message is being printed without color; on top there is the text *** Reading in the color of the reading device, i.e.:

*** Reading
<ownKeysRequester>
  <ownIdentities>
    <Identity>
      <address>alice@peptest.ch</address>
      <fpr>AB3D3A2F30EAB04BD69ACBA06019180C900624FC</fpr>
      <user-id>Phone</user-id>
      <username>Laptop of Alice Neuman</username>
      <comm-type>255</comm-type>
      <lang>en</lang>
    </Identity>
  </ownIdentities>
</ownKeysRequester>

The message flow can be reprinted:

test $ python3 sync_test.py -p | less -R

*** init pEp 1.1.1 (null) (null)

Phone_LQQMG15FQbDRHtL3cu3VWg.eml
2019-10-09 14:42:04.041957
<beacon>
  <challenge>F8 80 95 64 04 31 44 7B 83 9C 7C C8 AA CD 8B AC</challenge>
  <version>
    <major>1</major>
    <minor>2</minor>
  </version>
</beacon>


Laptop_x0N14cjR7ZKpZaf95MHo2g.eml
2019-10-09 14:42:04.143693
<beacon>
  <challenge>A1 30 1A F5 6C 8E 4A 82 88 19 A2 F7 61 0D 51 2C</challenge>
  <version>
    <major>1</major>
    <minor>2</minor>
  </version>
</beacon>

[…]

Minimail (minimail.py)

This small Python module is being used for the tests. It is simulating a small electronic mail implementation by having an inbox as the directory TestInbox. In this directory there are MIME message files, one file per message. Additionally, there are tag files per device. They’re there to have a time stamp when the TestInbox was last time checked. I.e.:

test $ ls -lT TestInbox/
total 264
-rw-r--r--  1 vb  staff      0 Oct  9 14:54:34 2019 Laptop
-rw-r--r--  1 vb  staff   8279 Oct  9 14:42:04 2019 Laptop_4zwSgMTPvuQbCoJSyBseng.eml
-rw-r--r--  1 vb  staff  17368 Oct  9 14:42:04 2019 Laptop_6YUxL9BVe3Ki7ZY04n6OfA.eml
-rw-r--r--  1 vb  staff   8218 Oct  9 14:42:04 2019 Laptop_dhKCcam3HS_G1Zw8PvYmbw.eml
-rw-r--r--  1 vb  staff   4112 Oct  9 14:42:04 2019 Laptop_mT-caVXjYCfpP06gz4BkXA.eml
-rw-r--r--  1 vb  staff   4112 Oct  9 14:42:04 2019 Laptop_x0N14cjR7ZKpZaf95MHo2g.eml
-rw-r--r--  1 vb  staff      0 Oct  9 14:54:34 2019 Phone
-rw-r--r--  1 vb  staff   4109 Oct  9 14:42:04 2019 Phone_LQQMG15FQbDRHtL3cu3VWg.eml
-rw-r--r--  1 vb  staff   8423 Oct  9 14:42:04 2019 Phone_MXqJi2tLBpelYrjC-yim3A.eml
-rw-r--r--  1 vb  staff   8411 Oct  9 14:42:04 2019 Phone_lzW23pWe2GqHpCokwG-20w.eml
-rw-r--r--  1 vb  staff  26002 Oct  9 14:42:05 2019 Phone_tbLviobuW7VlTQ0hHWrBVQ.eml
-rw-r--r--  1 vb  staff   8235 Oct  9 14:42:04 2019 Phone_vcmvxGLrkLoeeB4XEnEMng.eml

The timing of Minimail can be tweaked in minimail.py:27. I.e. by having timing = 2 Minimail will wait 2 seconds between the read and write functions.

Low level test: sync_handshake.py

The high level test program sync_test.py can be used for preparing the test environment. Then it is possible to use the low level test program sync_handshake.py directly to debug into p≡p engine’s and p≡p Python adapter’s code, as well as into the Python code of the test program itself.

Preparing the test environment

To prepare the test environment you can use:

test $ python3 sync_test.py -C # clean - delete all old test data
test $ python3 sync_test.py -s # setup a new test environment

When the test setup is being done you’ll find two directories, one for each of the two devices:

test $ ls -alF Phone Laptop
Laptop:
total 0
drwxr-xr-x   4 vb  staff  128 Oct  9 15:22 ./
drwxr-xr-x  21 vb  staff  672 Oct  9 15:22 ../
lrwxr-xr-x   1 vb  staff   17 Oct  9 15:22 Library@ -> /Users/vb/Library
lrwxr-xr-x   1 vb  staff   13 Oct  9 15:22 lib@ -> /Users/vb/lib

Phone:
total 0
drwxr-xr-x   4 vb  staff  128 Oct  9 15:22 ./
drwxr-xr-x  21 vb  staff  672 Oct  9 15:22 ../
lrwxr-xr-x   1 vb  staff   17 Oct  9 15:22 Library@ -> /Users/vb/Library
lrwxr-xr-x   1 vb  staff   13 Oct  9 15:22 lib@ -> /Users/vb/lib

These directories can be used as HOME directories when testing. The symlinks may vary depending on your operating system and on your setup. They’re for linking per user installations of libraries on development machines.

When a Sync test is being done the per user files of p≡p engine will appear in a subdirectory named .pEp/ each by default.

Executing a test for debugging the C++ and C code of p≡p Python adapter and p≡p engine

Low level Sync tests are best executed using two terminals, each for one device. Then it is possible to debug the two devices at the same time to see any functionality while it is executed.

To start a device in the debugger it is required to set environment variable HOME to the according directory and start sync_handshake.py like this:

test $ cd Phone
Phone $ HOME=$PWD lldb -- python3 ../sync_handshake.py -e Phone --color red
(lldb) target create "python3"
Current executable set to 'python3' (x86_64).
(lldb) settings set -- target.run-args  "../sync_handshake.py" "-e" "Phone" "--color" "red"
(lldb) _

In a second terminal you can do the same with the other device:

test $ cd Laptop
Laptop $ HOME=$PWD lldb -- python3 ../sync_handshake.py -e Laptop --color green
(lldb) target create "python3"
Current executable set to 'python3' (x86_64).
(lldb) settings set -- target.run-args  "../sync_handshake.py" "-e" "Laptop" "--color" "green"
(lldb) _

The options of the low level test program sync_handshake.py are documented in command line help:

Phone $ python3 ../sync_handshake.py --help

*** init pEp 1.1.1 (null) (null)
Usage: sync_handshake.py [options]

start a handshake test for one simulated device  this is being started once
per device by sync_test.py you can use this manually for debugging purposes
For debugging try:  $ cd $DEV && HOME=$PWD lldb python3 --
../sync_handshake.py -e $DEV

Options:
  -h, --help            show this help message and exit
  -e EXEC_FOR, --exec-for=EXEC_FOR
                        execute for name of simulated device (default: name of
                        actual directory)
  --color=COLOR         print debug output in this color
  --reject              reject device group
  --accept              accept device group (default)
  -E NOTIFICATIONS, --end-on=NOTIFICATIONS
                        end test on these notifications
  -j, --multi-threaded  use multithreaded instead of single threaded
                        implementation