189 lines
8.7 KiB
Markdown
189 lines
8.7 KiB
Markdown
# gVisor FUSE Test Suite
|
|
|
|
This is an integration test suite for fuse(4) filesystem. It runs under gVisor
|
|
sandbox container with VFS2 and FUSE function enabled.
|
|
|
|
This document describes the framework of FUSE integration test, how to use it,
|
|
and the guidelines that should be followed when adding new testing features.
|
|
|
|
## Integration Test Framework
|
|
|
|
By inheriting the `FuseTest` class defined in `linux/fuse_base.h`, every test
|
|
fixture can run in an environment with `mount_point_` mounted by a fake FUSE
|
|
server. It creates a `socketpair(2)` to send and receive control commands and
|
|
data between the client and the server. Because the FUSE server runs in the
|
|
background thread, gTest cannot catch its assertion failure immediately. Thus,
|
|
`TearDown()` function sends command to the FUSE server to check if all gTest
|
|
assertion in the server are successful and all requests and preset responses are
|
|
consumed.
|
|
|
|
## Communication Diagram
|
|
|
|
Diagram below describes how a testing thread communicates with the FUSE server
|
|
to achieve integration test.
|
|
|
|
For the following diagram, `>` means entering the function, `<` is leaving the
|
|
function, and `=` indicates sequentially entering and leaving. Not necessarily
|
|
follow exactly the below diagram due to the nature of a multi-threaded system,
|
|
however, it is still helpful to know when the client waits for the server to
|
|
complete a command and when the server awaits the next instruction.
|
|
|
|
```
|
|
| Client (Testing Thread) | Server (FUSE Server Thread)
|
|
| |
|
|
| >TEST_F() |
|
|
| >SetUp() |
|
|
| =MountFuse() |
|
|
| >SetUpFuseServer() |
|
|
| [create communication socket]|
|
|
| =fork() | =fork()
|
|
| [wait server complete] |
|
|
| | =ServerConsumeFuseInit()
|
|
| | =ServerCompleteWith()
|
|
| <SetUpFuseServer() |
|
|
| <SetUp() |
|
|
| [testing main] |
|
|
| | >ServerFuseLoop()
|
|
| | [poll on socket and fd]
|
|
| >SetServerResponse() |
|
|
| [write data to socket] |
|
|
| [wait server complete] |
|
|
| | [socket event occurs]
|
|
| | >ServerHandleCommand()
|
|
| | >ServerReceiveResponse()
|
|
| | [read data from socket]
|
|
| | [save data to memory]
|
|
| | <ServerReceiveResponse()
|
|
| | =ServerCompleteWith()
|
|
| <SetServerResponse() |
|
|
| | <ServerHandleCommand()
|
|
| >[Do fs operation] |
|
|
| [wait for fs response] |
|
|
| | [fd event occurs]
|
|
| | >ServerProcessFuseRequest()
|
|
| | =[read fs request]
|
|
| | =[save fs request to memory]
|
|
| | =[write fs response]
|
|
| <[Do fs operation] |
|
|
| | <ServerProcessFuseRequest()
|
|
| |
|
|
| =[Test fs operation result] |
|
|
| |
|
|
| >GetServerActualRequest() |
|
|
| [write data to socket] |
|
|
| [wait data from server] |
|
|
| | [socket event occurs]
|
|
| | >ServerHandleCommand()
|
|
| | >ServerSendReceivedRequest()
|
|
| | [write data to socket]
|
|
| [read data from socket] |
|
|
| [wait server complete] |
|
|
| | <ServerSendReceivedRequest()
|
|
| | =ServerCompleteWith()
|
|
| <GetServerActualRequest() |
|
|
| | <ServerHandleCommand()
|
|
| |
|
|
| =[Test actual request] |
|
|
| |
|
|
| >TearDown() |
|
|
| ... |
|
|
| >GetServerNumUnsentResponses() |
|
|
| [write data to socket] |
|
|
| [wait server complete] |
|
|
| | [socket event arrive]
|
|
| | >ServerHandleCommand()
|
|
| | >ServerSendData()
|
|
| | [write data to socket]
|
|
| | <ServerSendData()
|
|
| | =ServerCompleteWith()
|
|
| [read data from socket] |
|
|
| [test if all succeeded] |
|
|
| <GetServerNumUnsentResponses() |
|
|
| | <ServerHandleCommand()
|
|
| =UnmountFuse() |
|
|
| <TearDown() |
|
|
| <TEST_F() |
|
|
```
|
|
|
|
## Running the tests
|
|
|
|
Based on syscall tests, FUSE tests generate targets only with vfs2 and fuse
|
|
enabled. The corresponding targets end in `_fuse`.
|
|
|
|
For example, to run fuse test in `stat_test.cc`:
|
|
|
|
```bash
|
|
$ bazel test //test/fuse:stat_test_runsc_ptrace_vfs2_fuse
|
|
```
|
|
|
|
Test all targets tagged with fuse:
|
|
|
|
```bash
|
|
$ bazel test --test_tag_filters=fuse //test/fuse/...
|
|
```
|
|
|
|
## Writing a new FUSE test
|
|
|
|
1. Add test targets in `BUILD` and `linux/BUILD`.
|
|
2. Inherit your test from `FuseTest` base class. It allows you to:
|
|
- Fork a fake FUSE server in background during each test setup.
|
|
- Create a pair of sockets for communication and provide utility
|
|
functions.
|
|
- Stop FUSE server and check if error occurs in it after test completes.
|
|
3. Build the expected opcode-response pairs of your FUSE operation.
|
|
4. Call `SetServerResponse()` to preset the next expected opcode and response.
|
|
5. Do real filesystem operations (FUSE is mounted at `mount_point_`).
|
|
6. Check FUSE response and/or errors.
|
|
7. Retrieve FUSE request by `GetServerActualRequest()`.
|
|
8. Check if the request is as expected.
|
|
|
|
A few customized matchers used in syscalls test are encouraged to test the
|
|
outcome of filesystem operations. Such as:
|
|
|
|
```cc
|
|
SyscallSucceeds()
|
|
SyscallSucceedsWithValue(...)
|
|
SyscallFails()
|
|
SyscallFailsWithErrno(...)
|
|
```
|
|
|
|
Please refer to [test/syscalls/README.md](../syscalls/README.md) for further
|
|
details.
|
|
|
|
## Writing a new FuseTestCmd
|
|
|
|
A `FuseTestCmd` is a control protocol used in the communication between the
|
|
testing thread and the FUSE server. Such commands are sent from the testing
|
|
thread to the FUSE server to set up, control, or inspect the behavior of the
|
|
FUSE server in response to a sequence of FUSE requests.
|
|
|
|
The lifecycle of a command contains following steps:
|
|
|
|
1. The testing thread sends a `FuseTestCmd` via socket and waits for
|
|
completion.
|
|
2. The FUSE server receives the command and does corresponding action.
|
|
3. (Optional) The testing thread reads data from socket.
|
|
4. The FUSE server sends a success indicator via socket after processing.
|
|
5. The testing thread gets the success signal and continues testing.
|
|
|
|
The success indicator, i.e. `WaitServerComplete()`, is crucial at the end of
|
|
each `FuseTestCmd` sent from the testing thread. Because we don't want to begin
|
|
filesystem operation if the requests have not been completely set up. Also, to
|
|
test FUSE interactions in a sequential manner, concurrent requests are not
|
|
supported now.
|
|
|
|
To add a new `FuseTestCmd`, one must comply with following format:
|
|
|
|
1. Add a new `FuseTestCmd` enum class item defined in `linux/fuse_base.h`
|
|
2. Add a `SetServerXXX()` or `GetServerXXX()` public function in `FuseTest`.
|
|
This is how the testing thread will call to send control message. Define how
|
|
many bytes you want to send along with the command and what you will expect
|
|
to receive. Finally it should block and wait for a success indicator from
|
|
the FUSE server.
|
|
3. Add a handler logic in the switch condition of `ServerHandleCommand()`. Use
|
|
`ServerSendData()` or declare a new private function such as
|
|
`ServerReceiveXXX()` or `ServerSendXXX()`. It is mandatory to set it private
|
|
since only the FUSE server (forked from `FuseTest` base class) can call it.
|
|
This is the server part of the specific `FuseTestCmd` and the format of the
|
|
data should be consistent with what the client expects in the previous step.
|