1# Testing
2
3[TOC]
4
5## Overview
6
7Hafnium has 4 main kinds of tests:
8
91.  Host tests
10    *   Unit tests of core functionality, e.g. page table manipulation.
11    *   Source in `src/*_test.cc`.
12    *   Using the [Google Test](https://github.com/google/googletest) framework,
13        built against 'fake' architecture (`src/arch/fake`).
141.  Arch tests
15    *   Architecture-specific unit tests, e.g. MMU setup.
16    *   Source under `test/arch`.
17    *   Using our own _hftest_ framework, with `standalone_main.c`.
18    *   Build own hypervisor image, run in EL2.
191.  VM API tests
20    *   Exercise hypervisor API from both primary and secondary VMs.
21    *   Source under `test/vmapi`.
22    *   Tests are run from the primary VM under a normal build of the Hafnium
23        hypervisor, possibly communicating with a helper service in one or more
24        secondary VMs.
25    *   Using our own _hftest_ framework, with `standalone_main.c` for the
26        primary VM and `service.c` for secondary VMs.
27    *   Build own primary and secondary VMs, run in EL1 under actual Hafnium
28        image.
291.  Linux tests
30    *   Exercise the Hafnium Linux kernel module.
31    *   Source under `test/linux`.
32    *   Tests are run from userspace (PID 1) under Linux in the primary VM under
33        Hafnium, possibly with other secondary VMs.
34    *   Using our own _hftest_ framework, with `linux_main.c`.
35
36Host tests run directly on the host machine where they are built, whereas the
37other 3 types can run under an emulator such as QEMU, or on real hardware.
38
39## Presubmit
40
41Presubmit builds everything, runs all tests and checks the source for formatting
42and lint errors. This can be run locally with:
43
44```shell
45./kokoro/build.sh
46```
47
48Or to just run the tests after having built everything manually run:
49
50```shell
51./kokoro/test.sh
52```
53
54## QEMU tests
55
56These tests boot Hafnium on QEMU and the VMs make calls to Hafnium to test its
57behaviour. They can also be run on the Arm [FVP](FVP.md) and in some cases on
58real hardware.
59
60### hftest
61
62Having a framework for tests makes them easier to read and write. _hftest_ is a
63framework to meet the needs of VM based tests for Hafnium. It consists of:
64
65*   assertions
66*   test declarations
67*   base VM image
68*   driver script
69
70Assertions should be familiar from other testing libraries. They make use of
71C11's `_Generic` expressions for type genericity.
72
73Test declarations name the test and the suite that the test is part of.
74Declarations are converted into descriptors stored in the `.hftest` section of
75the VM image which allows the image to inspect the structure of the tests it
76contains. The linker sorts the descriptors by their symbol name which is how
77descriptors from the same suite are grouped together for easier parsing.
78
79The base VM image offers a command line interface, via the bootargs, to query
80the tests in the image and to run specific tests. The driver script uses this
81interface to execute tests, each with a fresh QEMU boot to give a fresh
82environment.
83