Debian Codegraph @

.cargo/vendor/regex-automata/tests/gen/README.md

raw
1 This directory contains tests for serialized objects from the regex-automata
2 crate. Currently, there are only two supported such objects: dense and sparse
3 DFAs.
4
5 The idea behind these tests is to commit some serialized objects and run some
6 basic tests by deserializing them and running searches and ensuring they are
7 correct. We also make sure these are run under Miri, since deserialization is
8 one of the biggest places where undefined behavior might occur in this crate
9 (at the time of writing).
10
11 The main thing we're testing is that the *current* code can still deserialize
12 *old* objects correctly. Generally speaking, compatibility extends to semver
13 compatible releases of this crate. Beyond that, no promises are made, although
14 in practice callers can at least depend on errors occurring. (The serialized
15 format always includes a version number, and incompatible changes increment
16 that version number such that an error will occur if an unsupported version is
17 detected.)
18
19 To generate the dense DFAs, I used this command:
20
21 ```
22 $ regex-cli generate serialize dense regex \
23 MULTI_PATTERN_V2 \
24 tests/gen/dense/ \
25 --rustfmt \
26 --safe \
27 --starts-for-each-pattern \
28 --specialize-start-states \
29 --start-kind both \
30 --unicode-word-boundary \
31 --minimize \
32 '\b[a-zA-Z]+\b' \
33 '(?m)^\S+$' \
34 '(?Rm)^\S+$'
35 ```
36
37 And to generate the sparse DFAs, I used this command, which is the same as
38 above, but with `s/dense/sparse/g`.
39
40 ```
41 $ regex-cli generate serialize sparse regex \
42 MULTI_PATTERN_V2 \
43 tests/gen/sparse/ \
44 --rustfmt \
45 --safe \
46 --starts-for-each-pattern \
47 --specialize-start-states \
48 --start-kind both \
49 --unicode-word-boundary \
50 --minimize \
51 '\b[a-zA-Z]+\b' \
52 '(?m)^\S+$' \
53 '(?Rm)^\S+$'
54 ```
55
56 The idea is to try to enable as many of the DFA's options as possible in order
57 to test that serialization works for all of them.
58
59 Arguably we should increase test coverage here, but this is a start. Note
60 that in particular, this does not need to test that serialization and
61 deserialization correctly roundtrips on its own. Indeed, the normal regex test
62 suite has a test that does a serialization round trip for every test supported
63 by DFAs. So that has very good coverage. What we're interested in testing here
64 is our compatibility promise: do DFAs generated with an older revision of the
65 code still deserialize correctly?