1The shell script run-sample-tests.sh runs selected Zephyr samples against
2the network test applications Docker container provided by the 'net-tools'
3Zephyr project, https://github.com/zephyrproject-rtos/net-tools.
4
5
6Installation
7************
8
9As a prerequisite it is assumed that Docker is installed and that the
10'net-tools' Docker container has been created, see the first bullet point
11at the net-tools Docker README file
12https://github.com/zephyrproject-rtos/net-tools/blob/master/README.docker.
13
14In essence, the following needs to be done:
15
16 * Install Docker
17 * Check out the net-tools project from github or update it with west
18 * Change working directory to the net-tools repository
19 * cd docker/
20 * Run 'docker build -t net-tools .'
21
22This creates a Docker image called 'net-tools' which the script will need as
23its counterpart when testing various network sample applications.
24
25
26Using
27*****
28
29The scripts/net/run-sample-tests.sh shell script can be used in two ways:
30
311. From a Zephyr network sample test directory.
32   Example:
33
34   cd samples/net/gptp
35   $ZEPHYR_BASE/scripts/net/run-sample-tests.sh
36
372. By giving the test directories as parameters to the runner script.
38   Example:
39
40   cd $ZEPHYR_BASE
41   ./scripts/net/run-sample-tests.sh samples/net/gptp \
42                                     samples/net/sockets/echo_server
43
44User can see what samples are supported like this:
45
46   $ZEPHYR_BASE/scripts/net/run-sample-tests.sh --scan
47
48The Docker container and a corresponding 'net-tools0' Docker network is started
49by the script, as well as Zephyr using native_posix board. IP addresses are
50assigned to the Docker network, which is a Linux network bridge interface.
51The default IP addresses are:
52
53 * Zephyr uses addresses 192.0.2.1 and 2001:db8::1
54 * Docker net-tools image uses addresses 192.0.2.2 and 2001:db8::2
55 * The Docker bridge interface uses addresses 192.0.2.254 and 2001:db8::254
56
57The default IP addresses are used by echo_client and mqtt_publisher, but
58with the echo_server the IP addresses are switched between Zephyr and Docker
59so that the echo_client application always uses addresses ending in .1 and
60the echo_server application uses those ending in .2. The script does the IP
61address setup for each sample test, be it the default ones or the switched
62ones.
63
64When completed, the return value, either from Zephyr or from the Docker
65container, is returned to the script on Zephyr or Docker application
66termination. The return value is used as a simple verdict whether the sample
67passed or failed.
68
69
70Directories
71***********
72
73The sample test script tries to automatically figure out the Zephyr base
74directory, which is assumed to be set by the ZEPHYR_BASE environment variable.
75Should this not be the case, the directory can be set using '-Z' or
76'--zephyr-dir' command line arguments. The sample test script also assumes
77that the net-tools git repository containing the Docker networking setup file
78'docker.conf' exists at the same directory level as the Zephyr base directory.
79If the net tools are found elsewhere, the net-tools directory can be set with
80the 'N' or '--net-tools-dir' command line argument.
81
82Help is also available using the 'h' or '--help' argument.
83