fuchsia_fuzzctl_test/
test.rs

1// Copyright 2022 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5use crate::controller::FakeController;
6use crate::writer::BufferSink;
7use anyhow::{Context as _, Result, anyhow, bail};
8use flex_fuchsia_fuzzer as fuzz;
9use fuchsia_fuzzctl::{Writer, create_artifact_dir, create_corpus_dir};
10use serde_json::json;
11use std::cell::RefCell;
12use std::fmt::{Debug, Display};
13use std::path::{Path, PathBuf};
14use std::rc::Rc;
15use std::{env, fs};
16use tempfile::{TempDir, tempdir};
17
18#[cfg(feature = "fdomain")]
19use std::sync::Arc;
20
21pub const TEST_URL: &str = "fuchsia-pkg://fuchsia.com/fake#meta/foo-fuzzer.cm";
22
23/// General purpose test context for the `ffx fuzz` plugin unit tests.
24///
25/// This object groups several commonly used routines used to capture data produced as a part of
26/// unit tests, such as:
27///
28///   * It can create temporary files and directories, and ensure they persist for duration of
29///     the test.
30///   * It maintains a list of expected outputs.
31///   * It shares a list of actual outputs with a `BufferSink` and can verify that they match
32///     its expectations.
33///   * It can produce `Writer`s backed by its associated `BufferSink`.
34///
35#[derive(Clone, Debug)]
36pub struct Test {
37    // This temporary directory is used indirectly via `root_dir`, but must be kept in scope for
38    // the duration of the test to avoid it being deleted prematurely.
39    _tmp_dir: Rc<Option<TempDir>>,
40    root_dir: PathBuf,
41    url: Rc<RefCell<Option<String>>>,
42    controller: FakeController,
43    requests: Rc<RefCell<Vec<String>>>,
44    expected: Vec<Expectation>,
45    actual: Rc<RefCell<Vec<u8>>>,
46    writer: Writer<BufferSink>,
47    #[cfg(feature = "fdomain")]
48    client: Arc<flex_client::Client>,
49}
50
51// Output can be tested for exact matches or substring matches.
52#[derive(Clone, Debug)]
53pub enum Expectation {
54    Equals(String),
55    Contains(String),
56}
57
58impl Test {
59    /// Creates a new `Test`.
60    ///
61    /// When running tests, users may optionally set the FFX_FUZZ_ECHO_TEST_OUTPUT environment
62    /// variable, which will cause this object to use an existing directory rather than create a
63    /// temporary one.
64    pub fn try_new() -> Result<Self> {
65        let (tmp_dir, root_dir) = match env::var("FFX_FUZZ_TEST_ROOT_DIR") {
66            Ok(root_dir) => (None, PathBuf::from(root_dir)),
67            Err(_) => {
68                let tmp_dir = tempdir().context("failed to create test directory")?;
69                let root_dir = PathBuf::from(tmp_dir.path());
70                (Some(tmp_dir), root_dir)
71            }
72        };
73        let actual = Rc::new(RefCell::new(Vec::new()));
74        let mut writer = Writer::new(BufferSink::new(Rc::clone(&actual)));
75        writer.use_colors(false);
76
77        #[cfg(feature = "fdomain")]
78        let client = fdomain_local::local_client_empty();
79
80        Ok(Self {
81            _tmp_dir: Rc::new(tmp_dir),
82            root_dir,
83            url: Rc::new(RefCell::new(None)),
84            controller: FakeController::new(),
85            requests: Rc::new(RefCell::new(Vec::new())),
86            expected: Vec::new(),
87            actual,
88            writer,
89            #[cfg(feature = "fdomain")]
90            client,
91        })
92    }
93
94    /// Returns a "domain" provider for this test.
95    ///
96    /// This returns an object that can be used to create sockets, channels, etc. that are
97    /// compatible with the transport being tested.
98    pub fn domain(&self) -> flex_client::ClientArg {
99        #[cfg(feature = "fdomain")]
100        return Arc::clone(&self.client);
101        #[cfg(not(feature = "fdomain"))]
102        return flex_client::fidl::ZirconClient;
103    }
104
105    /// Creates a proxy and server end for a protocol.
106    pub fn create_proxy<P: flex_client::fidl::ProtocolMarker>(
107        &self,
108    ) -> (P::Proxy, flex_client::fidl::ServerEnd<P>) {
109        #[cfg(feature = "fdomain")]
110        return self.client.create_proxy::<P>();
111        #[cfg(not(feature = "fdomain"))]
112        return flex_client::fidl::create_proxy::<P>();
113    }
114
115    /// Returns the writable temporary directory for this test.
116    pub fn root_dir(&self) -> &Path {
117        self.root_dir.as_path()
118    }
119
120    /// Creates a directory under this object's `root_dir`.
121    ///
122    /// The given `path` may be relative or absolute, but if it is the latter it must be
123    /// prefixed with this object's `root_dir`.
124    ///
125    /// Returns a `PathBuf` on success and an error if the `path` is outside the `root_dir` or
126    /// the filesystem returns an error.
127    ///
128    pub fn create_dir<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf> {
129        let path = path.as_ref();
130        let mut abspath = PathBuf::from(self.root_dir());
131        if path.is_relative() {
132            abspath.push(path);
133        } else if path.starts_with(self.root_dir()) {
134            abspath = PathBuf::from(path);
135        } else {
136            bail!(
137                "cannot create test directories outside the test root: {}",
138                path.to_string_lossy()
139            );
140        }
141        fs::create_dir_all(&abspath).with_context(|| {
142            format!("failed to create '{}' directory", abspath.to_string_lossy())
143        })?;
144        Ok(abspath)
145    }
146
147    /// Returns the path where the fuzzer will store artifacts.
148    pub fn artifact_dir(&self) -> PathBuf {
149        create_artifact_dir(&self.root_dir).unwrap()
150    }
151
152    /// Returns the path where the fuzzer will store its corpus of the given type.
153    pub fn corpus_dir(&self, corpus_type: fuzz::Corpus) -> PathBuf {
154        create_corpus_dir(&self.root_dir, corpus_type).unwrap()
155    }
156
157    /// Creates a fake "tests.json" file for testing.
158    ///
159    /// The "tests.json" will be created under the `relative_path` from this object's `root_dir`
160    /// and will contain the given `contents`. Except for some `util::tests`, unit tests should
161    /// prefer `create_tests_json`.
162    ///
163    /// Returns an error if any filesystem operations fail.
164    ///
165    pub fn write_tests_json<P: AsRef<Path>, S: AsRef<str>>(
166        &self,
167        build_dir: P,
168        contents: S,
169    ) -> Result<PathBuf> {
170        let build_dir = build_dir.as_ref();
171        let mut tests_json = PathBuf::from(build_dir);
172        tests_json.push("tests.json");
173        fs::write(&tests_json, contents.as_ref())
174            .with_context(|| format!("failed to write to '{}'", tests_json.to_string_lossy()))?;
175        Ok(tests_json)
176    }
177
178    /// Creates a fake "tests.json" file for testing.
179    ///
180    /// The "tests.json" will include an array of valid JSON objects for the given `urls`.
181    ///
182    /// Returns an error if any filesystem operations fail.
183    ///
184    pub fn create_tests_json<D: Display>(&self, urls: impl Iterator<Item = D>) -> Result<PathBuf> {
185        let build_dir = self
186            .create_dir("out/default")
187            .context("failed to create build directory for 'tests.json'")?;
188
189        let json_data: Vec<_> = urls
190            .map(|url| {
191                json!({
192                    "test": {
193                        "build_rule": "fuchsia_fuzzer_package",
194                        "package_url": url.to_string()
195                    }
196                })
197            })
198            .collect();
199        let json_data = json!(json_data);
200        self.write_tests_json(&build_dir, json_data.to_string()).with_context(|| {
201            format!("failed to create '{}/tests.json'", build_dir.to_string_lossy())
202        })
203    }
204
205    /// Creates several temporary `files` from the given iterator for testing.
206    ///
207    /// Each file's contents will simpl be its name, which is taken from the given `files`.
208    ///
209    /// Returns an error if writing to the filesystem fails.
210    ///
211    pub fn create_test_files<P: AsRef<Path>, D: Display>(
212        &self,
213        test_dir: P,
214        files: impl Iterator<Item = D>,
215    ) -> Result<()> {
216        let test_dir = self.create_dir(test_dir)?;
217        for filename in files {
218            let filename = filename.to_string();
219            fs::write(test_dir.join(&filename), filename.as_bytes())
220                .with_context(|| format!("failed to write to '{}'", filename))?;
221        }
222        Ok(())
223    }
224
225    /// Clones the `RefCell` holding the URL provided to the fake manager.
226    pub fn url(&self) -> Rc<RefCell<Option<String>>> {
227        self.url.clone()
228    }
229
230    /// Clones the fake fuzzer controller "connected" by the fake manager.
231    pub fn controller(&self) -> FakeController {
232        self.controller.clone()
233    }
234
235    /// Records a FIDL request made to a test fake.
236    pub fn record<S: AsRef<str>>(&mut self, request: S) {
237        let mut requests_mut = self.requests.borrow_mut();
238        requests_mut.push(request.as_ref().to_string());
239    }
240
241    /// Returns the recorded FIDL requests.
242    ///
243    /// As a side-effect, this resets the recorded requests.
244    ///
245    pub fn requests(&mut self) -> Vec<String> {
246        let mut requests_mut = self.requests.borrow_mut();
247        let requests = requests_mut.clone();
248        *requests_mut = Vec::new();
249        requests
250    }
251
252    /// Adds an expectation that an output written to the `BufferSink` will exactly match `msg`.
253    pub fn output_matches<T: AsRef<str> + Display>(&mut self, msg: T) {
254        let msg = msg.as_ref().trim().to_string();
255        if !msg.is_empty() {
256            self.expected.push(Expectation::Equals(msg));
257        }
258    }
259
260    /// Adds an expectation that an output written to the `BufferSink` will contain `msg`.
261    pub fn output_includes<T: AsRef<str> + Display>(&mut self, msg: T) {
262        let msg = msg.as_ref().trim().to_string();
263        if !msg.is_empty() {
264            self.expected.push(Expectation::Contains(msg));
265        }
266    }
267
268    /// Iterates over the expected and actual output and verifies expectations are met.
269    pub fn verify_output(&mut self) -> Result<()> {
270        let actual: Vec<u8> = {
271            let mut actual = self.actual.borrow_mut();
272            actual.drain(..).collect()
273        };
274        let actual = String::from_utf8_lossy(&actual);
275        let mut actual: Vec<String> = actual.split("\n").map(|s| s.trim().to_string()).collect();
276        actual.retain(|s| !s.is_empty());
277        let mut actual = actual.into_iter();
278
279        // `Contains` expectations may be surrounded by extra lines.
280        let mut extra = false;
281        for expectation in self.expected.drain(..) {
282            loop {
283                let line =
284                    actual.next().ok_or_else(|| anyhow!("unmet expectation: {:?}", expectation))?;
285                match &expectation {
286                    Expectation::Equals(msg) if line == *msg => {
287                        extra = false;
288                        break;
289                    }
290                    Expectation::Equals(_msg) if extra => continue,
291                    Expectation::Equals(msg) => {
292                        bail!("mismatch:\n  actual=`{}`\nexpected=`{}`", line, msg)
293                    }
294                    Expectation::Contains(msg) => {
295                        extra = true;
296                        if line.contains(msg) {
297                            break;
298                        }
299                    }
300                }
301            }
302        }
303        if !extra {
304            if let Some(line) = actual.next() {
305                bail!("unexpected line: {}", line);
306            }
307        }
308        Ok(())
309    }
310
311    /// Returns a `Writer` using the `BufferSink` associated with this object.
312    pub fn writer(&self) -> &Writer<BufferSink> {
313        &self.writer
314    }
315}
fuchsia_fuzzctl_test/test.rs

fuchsia_fuzzctl_test/
test.rs
