1# Contributing
2
3This is a cross-team project, aiming to build solid foundations for Rust UI libraries of all sorts.
4New contributions are extremely welcome!
5
6The basic process is simple:
7
81. Pick an [issue](https://github.com/DioxusLabs/taffy/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22), or [file a new one](https://github.com/DioxusLabs/taffy/issues/new).
92. Comment in the issue that you plan to tackle it, and the team will assign the task to you.
103. Submit a PR.
114. Respond to feedback from reviewers and make sure CI passes.
12
13The PR review process is completely open:  help us by commenting on, testing and approving PRs.
14
15If you'd like to help on a consistent basis or are interested in project management, create a Discussions post, and we'll be happy to hand out triage rights.
16
17## Testing
18
19### Running tests
20
21Flexbox layouts are tested by validating that layouts written in this crate perform the same as in Chrome.
22This is done by rendering an equivalent layout in HTML and then generating a Rust test case which asserts that the resulting layout is the same when run through our layout engine.
23
24You can run these tests without setting up a webdriver environment but if you are looking to add any test case you will need to install [chromedriver](http://chromedriver.chromium.org) and [Chrome](https://www.google.com/chrome/).
25If you are developing on macOS this is easy to do through brew.
26
27```bash
28brew install chromedriver
29```
30
31If you are Ubuntu, you will have to install `openssl` first,
32and then can follow [these instructions](https://tecadmin.net/setup-selenium-chromedriver-on-ubuntu/).
33Be sure that your Chrome vesion matches the downloaded `chromedriver` version!
34
35Once you have chromedriver installed and available in `PATH` you can re-generate all tests by running `cargo run --package gentest`. You should not manually update the tests in `tests/generated`. Instead, fix the script in `scripts/gentest/` and re-generate them. This can happen after a refactor. It can be helpful to commit the updated tests in a dedicated commit so that they can be easier to ignore during review.
36
37To add a new test case add another HTML file to `/test_fixtures` following the current tests as a template for new tests.
38
39### Writing tests
40
411. All tests should be wrapped in a module called `tests` gated by the standard `test` feature flag, to ensure they are not compiled unless tests are being run.
42
43    ```rs
44    #[cfg(test)]
45    mod tests {
46        // Place tests here
47    }
48    ```
49
502. For unit-testing this should be placed in the same file as the code they are testing
51    1. If files become extremely long (more than a couple thousand lines of code), tests should be split out into its own file under the same module
52
53    ```rs
54    // file: ./src/my_struct.rs
55    struct MyStruct;
56
57    impl MyStruct {
58        fn some_method() { .. }
59    }
60
61    #[cfg(test)]
62    mod tests {
63        #[test]
64        fn test_of_some_method() { .. }
65    }
66    ```
67
683. For integration tests this should be placed within the `./tests` folder
69
70    ```rs
71    // file: ./tests/my_integration_test.rs
72    #[test]
73    fn integration_test_one() { .. }
74    #[test]
75    fn integration_test_two() { .. }
76    ```
77
784. Each test should have a clear intent
79    1. It should be evident what is being tested (naming, code, comments)
80    2. When this test fails, it should be easy to understand what went wrong
81    3. Fixture-based tests (`#[rstest]`) can help improve clarity when many related scenarios need to be checked
82
83## Benchmarking
84
85Benchmarks build on the same infrastructure as testing, and actually benchmarks are automatically generated from test fixtures just like tests.
86Run `cargo bench` to run benchmarks locally.