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## The "just" task runner
18
19Taffy uses a task runner called [just](github.com/casey/just) to run tasks. This can be installed by running `cargo install --locked just`. This is just necessary for the commands of the form `just ...` to work.
20If you do you not want to install `just` then you can peak into the `justfile` in the root of this repo to see the equivalent cargo command, which will usually be of the form `cargo run -rp <package> ...`.
21
22## Testing
23
24### Running tests
25
26Flexbox layouts are tested by validating that layouts written in this crate perform the same as in Chrome.
27This 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.
28
29You 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/).
30If you are developing on macOS this is easy to do through brew.
31
32```bash
33brew install chromedriver
34```
35
36If you are Ubuntu, you will have to install `openssl` first,
37and then can follow [these instructions](https://tecadmin.net/setup-selenium-chromedriver-on-ubuntu/).
38Be sure that your Chrome version matches the downloaded `chromedriver` version!
39
40Once you have chromedriver installed and available in `PATH` you can re-generate all tests by running `just 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.
41
42To add a new test case add another HTML file to `/test_fixtures` following the current tests as a template for new tests.
43
44**Note: test fixtures (HTML files in the `text_fixtures` directory) that begin with an "x" are considered disabled, and the test generation script will not generate a test for them (and as the test generation script overwrites the entire directory when generating tests, this means that prefixing an existing test with an "x" and then running the test generation script will delete that test)**
45
46### Writing tests
47
481. 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.
49
50    ```rs
51    #[cfg(test)]
52    mod tests {
53        // Place tests here
54    }
55    ```
56
572. For unit-testing this should be placed in the same file as the code they are testing
58    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
59
60    ```rs
61    // file: ./src/my_struct.rs
62    struct MyStruct;
63
64    impl MyStruct {
65        fn some_method() { .. }
66    }
67
68    #[cfg(test)]
69    mod tests {
70        #[test]
71        fn test_of_some_method() { .. }
72    }
73    ```
74
753. For integration tests this should be placed within the `./tests` folder
76
77    ```rs
78    // file: ./tests/my_integration_test.rs
79    #[test]
80    fn integration_test_one() { .. }
81    #[test]
82    fn integration_test_two() { .. }
83    ```
84
854. Each test should have a clear intent
86    1. It should be evident what is being tested (naming, code, comments)
87    2. When this test fails, it should be easy to understand what went wrong
88    3. Fixture-based tests (`#[rstest]`) can help improve clarity when many related scenarios need to be checked
89
90## Benchmarking
91
92Benchmarks build on the same infrastructure as testing, and actually benchmarks are automatically generated from test fixtures just like tests.
93Run `just bench` to run benchmarks locally. To run head-to-head benchmarks with Yoga, run `just bench --features yoga`. You will need `libclang-dev` or the xcode commandline tools installed in order to run the yoga benchmarks.