Engine/Testing p≡p Sync
Prerequisites
- p≡p Sync can be tested using p≡p Python adapter.
- 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
implementationThe 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.pyIf 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:1523All 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.emlThe 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 environmentWhen 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/libThese 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
-L, --leave-device-group
after a successful sync run this to make the device
leave the device group againTest of leave_device_group()
This test is requiring an already synced device group. Then one device is triggered to leave the device group. It will reset its keys. The remaining devices will do an unled key reset.
Prepare synced device group of three devices
~ $ cd pEpPythonAdapter/test
test $ python3 sync_test.py -C # clear data
test $ python3 sync_test.py # sync for two devices
test $ python3 sync_test.py -3 # sync third device in
test $ python3 sync_test.py -b # backup state for later recoveryTell Phone to leave device group; the others remain in group
Terminal 1:
test $ cd Laptop
Laptop $ HOME=$PWD lldb -- python3 ../sync_handshake.py -e Phone --color greenTerminal 2:
test $ cd Pad
Pad $ HOME=$PWD lldb -- python3 ../sync_handshake.py -e Phone --color cyanTerminal 3:
start Phone with added parameter -L to leave
test $ cd Phone
Phone $ HOME=$PWD lldb -- python3 ../sync_handshake.py -e Phone --color red -L