yew/CONTRIBUTING.md

Contribution Guide

Setting up your local development environment

Add the wasm target

rustup target add wasm32-unknown-unknown

Build

cargo build --target wasm32-unknown-unknown

stdweb

To run the examples in ./yew-stdweb, you may wish to install cargo-web:

cargo install cargo-web

Tests

Yew has unit tests which run via cargo test. However, a browser is required to run a large portion of the tests. This section will guide you through the process of running these tests locally.

Integration Tests

First, install wasm-pack. Instructions

wasm-pack automatically takes care of installing the correct wasm-bindgen version and downloading a WebDriver for the browser.

The following command is all you need to run the tests:

wasm-pack test --firefox --headless -- --features wasm_test

You can replace --firefox with --chrome or --safari if you want to run the tests in a different browser. Currently, Yew's CI tests use Firefox.

Make sure to run the command in the directory of the crate you wish to test (e.g. yew or yewtil). If you run the command in the repository root you will get an error like this:

Error: failed to parse manifest: yew/Cargo.toml
Caused by: missing field `package`

Manually installing a WebDriver

wasm-pack automatically downloads the selected WebDriver for you. If desired, you can download a WebDriver manually. For instructions, please consult the documentation of the WebDriver you wish to install.

You might want to pass the argument --mode no-install to wasm-pack to make sure it doesn't try to install something. If the WebDriver binary is in the path, you can use the same command as above to run the tests. If not, you need to tell wasm-pack test where to find it using the --geckodriver, --chromedriver, or --safaridriver option. Run wasm-pack test --help to learn more.

Running all tests

You can use the /ci/run_tests.sh script to run all tests, which is the same script that is used by Yew's CI to run the whole test suite. The script currently always runs the tests in Firefox.

Fetch service tests

The following only applies to the yew (and yew-stdweb) crate.

The tests for the fetch service require a local httpbin server. We recommend running this with Docker:

docker run -p 8000:80 kennethreitz/httpbin

Before running the tests, you need to set the HTTPBIN_URL environment variable to the URL of your httpbin instance. If you used the previous command to start the server the value should be "http://localhost:8000" (You mustn't add a trailing slash).

# Unix-like
export HTTPBIN_URL="http://localhost:8000"

# Windows
set HTTPBIN_URL=http://localhost:8000

You also need to activate the httpbin_test feature for the tests to run:

wasm-pack test --firefox --headless -- --features wasm_test,httpbin_test

If you're using the /ci/run_tests.sh script you only need to set the environment variable. The script will automatically add the feature.

Macro tests

When adding or updating tests, please make sure you have updated the appropriate stderr file, which you can find here for the html! macro. These files ensure that macro compilation errors are correct and easy to understand.

To update or generate a new stderr file you can run TRYBUILD=overwrite cargo test --test macro_test or TRYBUILD=overwrite cargo test --test derive_props_test from the yew-macro directory.

Benchmarks

If you wish to improve the performance of Yew, we ask you to prove the improvements of your changes through benchmarking.

1. Fork and clone yewstack/js-framework-benchmark
2. Update frameworks/yew/Cargo.toml with your fork of Yew and the branch for your changes
3. Open a new PR with your Cargo.toml changes

Feel free to add new benchmark tests if the current benchmark coverage is insufficient!

Writing APIs

When building new APIs, think about what it would be like to use them. Would this API cause confusing and hard to pin error mesages? Would this API integrate well with other APIs? Is it intuitive to use this API?

Below, you can find some useful guidance and best practices on how to write APIs. These are only guidelines and while they are helpful and should be followed where possible, in some cases, it may not be possible to do so.

• The Rust API Guidelines
• Elegant Library APIs in Rust