1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
|
Directory Layout
================
- data
Data files for tests, such as reference images, vertex data, texture
images, etc.
- misc
If you want Crucible to play nicely with bash, zsh, vim, emacs, or whatever,
then look in misc/.
- src/tests
Source for the tests themselves.
- src/tests/examples
Example tests that demonstrate how to use the framework or how to accomplish
a tricky testing task.
- src/tests/func: Functional tests
- src/tests/stress: Stress tests
- src/tests/self: Self-tests for Crucible. Used by `make check`.
- include
Headers under include/ define each module's public API. This contrasts with
headers under src/, which are private to their containing directory.
- include/tapi
The test API. Functions that begin with 't_' may be called only inside
a running test thread.
- include/qonos
Wrappers around the Vulkan API that make life easier for test authors.
- include/util
Utilities that may be used by any module. They are safe to use inside or
outside running test threads. Consider this to be Crucible's "standard
library".
- include/framework
Crucible's framework APIs are off-limits to test code ( (that is, by code
under src/tests/).
Writing Tests
=============
Tests live in the 'src/tests' directory.
Tests have access to the APIs in the 'include/' directory (except
'include/framework/', which is reserved for Crucible's test framework).
After writing a test, you will likely need to generate a reference image for
it. The command 'crucible bootstrap' can generate one for you.
All images in the 'data' directory are available to tests. You can load an
image with `t_new_cru_image_from_filename(filename)`, where filename is
relative to the 'data' directory.
Generated Files
===============
The names of generated source files should match the glob "*_gen.[ch]".
Do not commit generated image files. They consume too much space in the git
history.
Do commit a generated source file if the diff of the generated file is
substantially more reviewable and informative than the diff of the generator
script. Often, small cryptic changes to a generator script will produce easily
understood changes in its generated files. As a corollary, if a generated file
is commited, then its generator script must produce deterministic output.
Do not commit a generated source file if it doesn't satisfy the "reviewability"
criterion above.
|
