mirror of
https://fuchsia.googlesource.com/third_party/pigweed.googlesource.com/pigweed/pigweed
synced 2024-09-21 14:16:26 +00:00
d0b2d48782
This change adds a pw_test_server module which implements a gRPC server for queueing and distributing unit tests across multiple test runners. The server is implemented as a Go library which can be imported and used by developers to build a custom unit test running infrastructure. To use the server, a UnitTestRunner interface that processes requests to run unit tests must be implemented and registered with the server. An implementation of this interface which runs unit test executables through an external command is provided alongside the server. An example program that uses the server library to run a unit test server is also provided within the module. This program uses the command-based test runners to run unit tests on a local machine. It is configurable through a config file, allowing multiple workers to be registered with the server. The program additionally doubles as a gRPC client for the server which can be invoked with the path to a unit test executable to schedule it to be run. Change-Id: I347d230370620395de09e277f9763d7df1c4abad
109 lines
3.5 KiB
ReStructuredText
109 lines
3.5 KiB
ReStructuredText
.. _chapter-test-server:
|
|
|
|
.. default-domain:: cpp
|
|
|
|
.. highlight:: sh
|
|
|
|
---------------
|
|
pw_test_server
|
|
---------------
|
|
The test server module implements a gRPC server which runs unit tests.
|
|
|
|
Overview
|
|
--------
|
|
The unit test server is responsible for processing requests to run unit tests
|
|
and distributing them among a pool of test workers that run in parallel. This
|
|
allows unit tests to be run across multiple devices simultaneously, greatly
|
|
speeding up their execution time.
|
|
|
|
Additionally, the server allows many tests to be queued up at once and scheduled
|
|
across available devices, making it possible to automatically run unit tests
|
|
from a Ninja build after code is updated. This integrates nicely with the
|
|
``pw watch`` command to re-run all affected unit tests after modifying code.
|
|
|
|
The test server is implemented as a library in various programming languages.
|
|
This library provides the core gRPC server and a mechanism through which unit
|
|
test worker routines can be registered. Code using the library instantiates a
|
|
server with some custom workers for the desired target to run scheduled unit
|
|
tests.
|
|
|
|
The pw_test_server module also provides a standalone ``pw_test_server`` program
|
|
which runs the test server with configurable workers that launch external
|
|
processes to run unit tests. This program should be sufficient to quickly get
|
|
unit tests running in a simple setup, such as multiple devices plugged into a
|
|
development machine.
|
|
|
|
Standalone executable
|
|
---------------------
|
|
This section describes how to use the ``pw_test_server`` program to set up a
|
|
simple unit test server with workers.
|
|
|
|
Configuration
|
|
^^^^^^^^^^^^^
|
|
The standalone server is configured from a file written in Protobuf text format
|
|
containing a ``pw.test_server.ServerConfig`` message as defined in
|
|
``//pw_test_server/config.proto``.
|
|
|
|
At least one ``worker`` message must be specified. Each of the workers refers to
|
|
a script or program which is invoked with the path to a unit test executable
|
|
file as a positional argument. Other arguments provided to the program must be
|
|
options/switches.
|
|
|
|
For example, the config file below defines two workers, each connecting to an
|
|
STM32F429I Discovery board with a specified serial number.
|
|
|
|
**server_config.txt**
|
|
|
|
.. code:: text
|
|
|
|
runner {
|
|
command: "stm32f429i_disc1_unit_test_runner"
|
|
args: "--openocd-config"
|
|
args: "targets/stm32f429i-disc1/py/stm32f429i_disc1_utils/openocd_stm32f4xx.cfg"
|
|
args: "--serial"
|
|
args: "066DFF575051717867013127"
|
|
}
|
|
|
|
runner {
|
|
command: "stm32f429i_disc1_unit_test_runner"
|
|
args: "--openocd-config"
|
|
args: "targets/stm32f429i-disc1/py/stm32f429i_disc1_utils/openocd_stm32f4xx.cfg"
|
|
args: "--serial"
|
|
args: "0667FF494849887767196023"
|
|
}
|
|
|
|
|
|
Running the server
|
|
^^^^^^^^^^^^^^^^^^
|
|
To start the standalone server, run the ``pw_test_server`` program with the
|
|
``-server`` flag and point it to your config file.
|
|
|
|
.. code:: text
|
|
|
|
$ pw_test_server -server -config server_config.txt -port 8080
|
|
|
|
|
|
Sending test requests
|
|
^^^^^^^^^^^^^^^^^^^^^
|
|
To request the server to run a unit test, the ``pw_test_server`` program is
|
|
run in client mode, specifying the path to the unit test executable through a
|
|
``-test`` option.
|
|
|
|
.. code:: text
|
|
|
|
$ pw_test_server -host localhost -port 8080 -test /path/to/my/test.elf
|
|
|
|
This command blocks until the test has run and prints out its output. Multiple
|
|
tests can be scheduled in parallel; the server will distribute them among its
|
|
available workers.
|
|
|
|
Library APIs
|
|
------------
|
|
To use the test server library in your own code, refer to one of its programming
|
|
language APIs below.
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
go/docs
|