1Thank you for your interest in contributing to fsnotify! We try to review and
2merge PRs in a reasonable timeframe, but please be aware that:
3
4- To avoid "wasted" work, please discuss changes on the issue tracker first. You
5 can just send PRs, but they may end up being rejected for one reason or the
6 other.
7
8- fsnotify is a cross-platform library, and changes must work reasonably well on
9 all supported platforms.
10
11- Changes will need to be compatible; old code should still compile, and the
12 runtime behaviour can't change in ways that are likely to lead to problems for
13 users.
14
15Testing
16-------
17Just `go test ./...` runs all the tests; the CI runs this on all supported
18platforms. Testing different platforms locally can be done with something like
19[goon] or [Vagrant], but this isn't super-easy to set up at the moment.
20
21Use the `-short` flag to make the "stress test" run faster.
22
23Writing new tests
24-----------------
25Scripts in the testdata directory allow creating test cases in a "shell-like"
26syntax. The basic format is:
27
28 script
29
30 Output:
31 desired output
32
33For example:
34
35 # Create a new empty file with some data.
36 watch /
37 echo data >/file
38
39 Output:
40 create /file
41 write /file
42
43Just create a new file to add a new test; select which tests to run with
44`-run TestScript/[path]`.
45
46script
47------
48The script is a "shell-like" script:
49
50 cmd arg arg
51
52Comments are supported with `#`:
53
54 # Comment
55 cmd arg arg # Comment
56
57All operations are done in a temp directory; a path like "/foo" is rewritten to
58"/tmp/TestFoo/foo".
59
60Arguments can be quoted with `"` or `'`; there are no escapes and they're
61functionally identical right now, but this may change in the future, so best to
62assume shell-like rules.
63
64 touch "/file with spaces"
65
66End-of-line escapes with `\` are not supported.
67
68### Supported commands
69
70 watch path [ops] # Watch the path, reporting events for it. Nothing is
71 # watched by default. Optionally a list of ops can be
72 # given, as with AddWith(path, WithOps(...)).
73 unwatch path # Stop watching the path.
74 watchlist n # Assert watchlist length.
75
76 stop # Stop running the script; for debugging.
77 debug [yes/no] # Enable/disable FSNOTIFY_DEBUG (tests are run in
78 parallel by default, so -parallel=1 is probably a good
79 idea).
80
81 touch path
82 mkdir [-p] dir
83 ln -s target link # Only ln -s supported.
84 mkfifo path
85 mknod dev path
86 mv src dst
87 rm [-r] path
88 chmod mode path # Octal only
89 sleep time-in-ms
90
91 cat path # Read path (does nothing with the data; just reads it).
92 echo str >>path # Append "str" to "path".
93 echo str >path # Truncate "path" and write "str".
94
95 require reason # Skip the test if "reason" is true; "skip" and
96 skip reason # "require" behave identical; it supports both for
97 # readability. Possible reasons are:
98 #
99 # always Always skip this test.
100 # symlink Symlinks are supported (requires admin
101 # permissions on Windows).
102 # mkfifo Platform doesn't support FIFO named sockets.
103 # mknod Platform doesn't support device nodes.
104
105
106output
107------
108After `Output:` the desired output is given; this is indented by convention, but
109that's not required.
110
111The format of that is:
112
113 # Comment
114 event path # Comment
115
116 system:
117 event path
118 system2:
119 event path
120
121Every event is one line, and any whitespace between the event and path are
122ignored. The path can optionally be surrounded in ". Anything after a "#" is
123ignored.
124
125Platform-specific tests can be added after GOOS; for example:
126
127 watch /
128 touch /file
129
130 Output:
131 # Tested if nothing else matches
132 create /file
133
134 # Windows-specific test.
135 windows:
136 write /file
137
138You can specify multiple platforms with a comma (e.g. "windows, linux:").
139"kqueue" is a shortcut for all kqueue systems (BSD, macOS).
140
141
142[goon]: https://github.com/arp242/goon
143[Vagrant]: https://www.vagrantup.com/
144[integration_test.go]: /integration_test.go