Vendor things

third-party/vendor/wasm-bindgen/guide/src/wasm-bindgen-test/asynchronous-tests.md

@@ -0,0 +1,37 @@
+# Writing Asynchronous Tests
+
+Not all tests can execute immediately and some may need to do "blocking" work
+like fetching resources and/or other bits and pieces. To accommodate this
+asynchronous tests are also supported through the `futures` and
+`wasm-bindgen-futures` crates.
+
+Writing an asynchronous test is pretty simple, just use an `async` function!
+You'll also likely want to use the `wasm-bindgen-futures` crate to convert JS
+promises to Rust futures.
+
+```rust
+use wasm_bindgen::prelude::*;
+use wasm_bindgen_futures::JsFuture;
+
+#[wasm_bindgen_test]
+async fn my_async_test() {
+    // Create a promise that is ready on the next tick of the micro task queue.
+    let promise = js_sys::Promise::resolve(&JsValue::from(42));
+
+    // Convert that promise into a future and make the test wait on it.
+    let x = JsFuture::from(promise).await.unwrap();
+    assert_eq!(x, 42);
+}
+```
+
+## Rust compiler compatibility
+
+Note that `async` functions are only supported in stable from Rust 1.39.0 and
+beyond.
+
+If you're using the `futures` crate from crates.io in its 0.1 version then
+you'll want to use the `0.3.*` version of `wasm-bindgen-futures` and the `0.2.8`
+version of `wasm-bindgen-test`. In those modes you'll also need to use
+`#[wasm_bindgen_test(async)]` instead of using an `async` function. In general
+we'd recommend using the nightly version with `async` since the user experience
+is much improved!

third-party/vendor/wasm-bindgen/guide/src/wasm-bindgen-test/browsers.md

@@ -0,0 +1,166 @@
+# Testing in Headless Browsers
+
+## Configure Your Test Crate
+
+Add this to the root of your test crate, e.g. `$MY_CRATE/tests/web.rs`:
+
+```rust
+use wasm_bindgen_test::wasm_bindgen_test_configure;
+
+wasm_bindgen_test_configure!(run_in_browser);
+```
+
+Or if you need to run your tests inside a web worker, you can also
+configured it using the `wasm_bindgen_test_configure` macro as following
+snippet.
+
+```rust
+use wasm_bindgen_test::wasm_bindgen_test_configure;
+
+// Run in dedicated worker.
+wasm_bindgen_test_configure!(run_in_dedicated_worker);
+// Or run in shared worker.
+wasm_bindgen_test_configure!(run_in_shared_worker);
+// Or run in service worker.
+wasm_bindgen_test_configure!(run_in_service_worker);
+```
+
+Note that although a particular test crate must target either headless browsers
+or Node.js, you can have test suites for both Node.js and browsers for your
+project by using multiple test crates. For example:
+
+```
+$MY_CRATE/
+`-- tests
+    |-- node.rs              # The tests in this suite use the default Node.js.
+    |-- dedicated_worker.rs  # The tests in this suite are configured for dedicated workers.
+    |-- shared_worker.rs     # The tests in this suite are configured for shared workers.
+    |-- service_worker.rs    # The tests in this suite are configured for service workers.
+    `-- web.rs               # The tests in this suite are configured for browsers.
+```
+
+## Configuring Which Browser is Used
+
+To control which browser is used for headless testing, use the appropriate flag
+with `wasm-pack test`:
+
+* `wasm-pack test --chrome` — Run the tests in Chrome. This machine must
+  have Chrome installed.
+
+* `wasm-pack test --firefox` — Run the tests in Firefox. This machine must
+  have Firefox installed.
+
+* `wasm-pack test --safari` — Run the tests in Safari. This machine must
+  have Safari installed.
+
+If multiple browser flags are passed, the tests will be run under each browser.
+
+## Running the Tests in the Headless Browser
+
+Once the tests are configured to run in a headless browser, just run `wasm-pack
+test` with the appropriate browser flags and `--headless`:
+
+```bash
+wasm-pack test --headless --chrome --firefox --safari
+```
+
+## Configuring Headless Browser capabilities
+
+Add the file `webdriver.json` to the root of your crate. Each browser has own 
+section for capabilities. For example:
+
+```json
+{
+  "moz:firefoxOptions": {
+    "prefs": {
+      "media.navigator.streams.fake": true,
+      "media.navigator.permission.disabled": true
+    },
+    "args": []
+  },
+  "goog:chromeOptions": {
+    "args": [
+      "--use-fake-device-for-media-stream",
+      "--use-fake-ui-for-media-stream"
+    ]
+  }
+}
+```
+Full list supported capabilities can be found:
+
+* for Chrome - [here](https://peter.sh/experiments/chromium-command-line-switches/)
+* for Firefox - [here](https://developer.mozilla.org/en-US/docs/Web/WebDriver/Capabilities/firefoxOptions)
+
+Note that the `headless` argument is always enabled for both browsers.
+
+### Debugging Headless Browser Tests
+
+Omitting the `--headless` flag will disable headless mode, and allow you to
+debug failing tests in your browser's devtools.
+
+--------------------------------------------------------------------------------
+
+## Appendix: Testing in headless browsers without `wasm-pack`
+
+**⚠️ The recommended way to use `wasm-bindgen-test` is with `wasm-pack`, since it
+will handle installing the test runner, installing a WebDriver client for your
+browser, and informing `cargo` how to use the custom test runner.** However, you
+can also manage those tasks yourself, if you wish.
+
+### Configuring Which Browser is Used
+
+If one of the following environment variables is set, then the corresponding
+WebDriver and browser will be used. If none of these environment variables are
+set, then the `$PATH` is searched for a suitable WebDriver implementation.
+
+#### `GECKODRIVER=path/to/geckodriver`
+
+Use Firefox for headless browser testing, and `geckodriver` as its
+WebDriver.
+
+The `firefox` binary must be on your `$PATH`.
+
+[Get `geckodriver` here](https://github.com/mozilla/geckodriver/releases)
+
+#### `CHROMEDRIVER=path/to/chromedriver`
+
+Use Chrome for headless browser testing, and `chromedriver` as its
+WebDriver.
+
+The `chrome` binary must be on your `$PATH`.
+
+[Get `chromedriver` here](http://chromedriver.chromium.org/downloads)
+
+#### `SAFARIDRIVER=path/to/safaridriver`
+
+Use Safari for headless browser testing, and `safaridriver` as its
+WebDriver.
+
+This is installed by default on Mac OS. It should be able to find your Safari
+installation by default.
+
+### Running the Tests in the Remote Headless Browser
+
+Tests can be run on a remote webdriver. To do this, the above environment 
+variables must be set as URL to the remote webdriver. For example:
+
+```
+CHROMEDRIVER_REMOTE=http://remote.host/
+```
+
+### Running the Tests in the Headless Browser
+
+Once the tests are configured to run in a headless browser and the appropriate
+environment variables are set, executing the tests for headless browsers is the
+same as executing them for Node.js:
+
+```bash
+cargo test --target wasm32-unknown-unknown
+```
+
+#### Debugging Headless Browser Tests
+
+Set the `NO_HEADLESS=1` environment variable and the browser tests will not run
+headless. Instead, the tests will start a local server that you can visit in
+your Web browser of choices, and headless testing should not be used. You can
+then use your browser's devtools to debug.

third-party/vendor/wasm-bindgen/guide/src/wasm-bindgen-test/continuous-integration.md

@@ -0,0 +1,74 @@
+# Setting Up Continuous Integration with `wasm-bindgen-test`
+
+This page contains example configurations for running `wasm-bindgen-test`-based
+tests in various CI services.
+
+Is your favorite CI service missing? [Send us a pull
+request!](https://github.com/rustwasm/wasm-bindgen)
+
+## Travis CI
+
+```yaml
+language: rust
+rust    : nightly
+
+addons:
+  firefox: latest
+  chrome : stable
+
+install:
+  - curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
+
+script:
+
+  # this will test the non wasm targets if your crate has those, otherwise remove this line.
+  #
+  - cargo test
+
+  - wasm-pack test --firefox --headless
+  - wasm-pack test --chrome  --headless
+```
+
+## AppVeyor
+
+```yaml
+install:
+  - ps: Install-Product node 10
+  - appveyor-retry appveyor DownloadFile https://win.rustup.rs/ -FileName rustup-init.exe
+  - rustup-init.exe -y --default-host x86_64-pc-windows-msvc --default-toolchain nightly
+  - set PATH=%PATH%;C:\Users\appveyor\.cargo\bin
+  - rustc -V
+  - cargo -V
+  - rustup target add wasm32-unknown-unknown
+  - cargo install wasm-bindgen-cli
+
+build: false
+
+test_script:
+  # Test in Chrome. chromedriver is installed by default in appveyor.
+  - set CHROMEDRIVER=C:\Tools\WebDriver\chromedriver.exe
+  - cargo test --target wasm32-unknown-unknown
+  - set CHROMEDRIVER=
+  # Test in Firefox. geckodriver is also installed by default.
+  - set GECKODRIVER=C:\Tools\WebDriver\geckodriver.exe
+  - cargo test --target wasm32-unknown-unknown
+```
+
+## GitHub Actions
+
+```yaml
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Install
+        run: curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
+
+      - run: cargo test
+      - run: wasm-pack test --headless --chrome
+      - run: wasm-pack test --headless --firefox
+```

third-party/vendor/wasm-bindgen/guide/src/wasm-bindgen-test/index.md

@@ -0,0 +1,17 @@
+# Testing on `wasm32-unknown-unknown` with `wasm-bindgen-test`
+
+The `wasm-bindgen-test` crate is an experimental test harness for Rust programs
+compiled to wasm using `wasm-bindgen` and the `wasm32-unknown-unknown`
+target.
+
+## Goals
+
+* Write tests for wasm as similar as possible to how you normally would write
+  `#[test]`-style unit tests for native targets.
+
+* Run the tests with the usual `cargo test` command but with an explicit wasm
+  target:
+
+  ```
+  cargo test --target wasm32-unknown-unknown
+  ```

third-party/vendor/wasm-bindgen/guide/src/wasm-bindgen-test/usage.md

@@ -0,0 +1,122 @@
+# Using `wasm-bindgen-test`
+
+### Add `wasm-bindgen-test` to Your `Cargo.toml`'s `[dev-dependencies]`
+
+```toml
+[dev-dependencies]
+wasm-bindgen-test = "0.3.0"
+```
+
+Note that the `0.3.0` track of `wasm-bindgen-test` supports Rust 1.39.0+, which
+is currently the nightly channel (as of 2019-09-05). If you want support for
+older compilers use the `0.2.*` track of `wasm-bindgen-test`.
+
+## Write Some Tests
+
+Create a `$MY_CRATE/tests/wasm.rs` file:
+
+```rust
+use wasm_bindgen_test::*;
+
+#[wasm_bindgen_test]
+fn pass() {
+    assert_eq!(1, 1);
+}
+
+#[wasm_bindgen_test]
+fn fail() {
+    assert_eq!(1, 2);
+}
+```
+
+Writing tests is the same as normal Rust `#[test]`s, except we are using the
+`#[wasm_bindgen_test]` attribute.
+
+One other difference is that the tests **must** be in the root of the crate, or
+within a `pub mod`. Putting them inside a private module will not work.
+
+## Execute Your Tests
+
+Run the tests with `wasm-pack test`. By default, the tests are generated to
+target Node.js, but you can [configure tests to run inside headless
+browsers](./browsers.html) as well.
+
+```shell
+$ wasm-pack test --node
+    Finished dev [unoptimized + debuginfo] target(s) in 0.11s
+     Running /home/.../target/wasm32-unknown-unknown/debug/deps/wasm-4a309ffe6ad80503.wasm
+running 2 tests
+
+test wasm::pass ... ok
+test wasm::fail ... FAILED
+
+failures:
+
+---- wasm::fail output ----
+    error output:
+        panicked at 'assertion failed: `(left == right)`
+          left: `1`,
+         right: `2`', crates/test/tests/wasm.rs:14:5
+
+    JS exception that was thrown:
+        RuntimeError: unreachable
+            at __rust_start_panic (wasm-function[1362]:33)
+            at rust_panic (wasm-function[1357]:30)
+            at std::panicking::rust_panic_with_hook::h56e5e464b0e7fc22 (wasm-function[1352]:444)
+            at std::panicking::continue_panic_fmt::had70ba48785b9a8f (wasm-function[1350]:122)
+            at std::panicking::begin_panic_fmt::h991e7d1ca9bf9c0c (wasm-function[1351]:95)
+            at wasm::fail::ha4c23c69dfa0eea9 (wasm-function[88]:477)
+            at core::ops::function::FnOnce::call_once::h633718dad359559a (wasm-function[21]:22)
+            at wasm_bindgen_test::__rt::Context::execute::h2f669104986475eb (wasm-function[13]:291)
+            at __wbg_test_fail_1 (wasm-function[87]:57)
+            at module.exports.__wbg_apply_2ba774592c5223a7 (/home/alex/code/wasm-bindgen/target/wasm32-unknown-unknown/wbg-tmp/wasm-4a309ffe6ad80503.js:61:66)
+
+
+failures:
+
+    wasm::fail
+
+test result: FAILED. 1 passed; 1 failed; 0 ignored
+
+error: test failed, to rerun pass '--test wasm'
+```
+
+That's it!
+
+--------------------------------------------------------------------------------
+
+## Appendix: Using `wasm-bindgen-test` without `wasm-pack`
+
+**⚠️ The recommended way to use `wasm-bindgen-test` is with `wasm-pack`, since it
+will handle installing the test runner, installing a WebDriver client for your
+browser, and informing `cargo` how to use the custom test runner.** However, you
+can also manage those tasks yourself, if you wish.
+
+In addition to the steps above, you must also do the following.
+
+### Install the Test Runner
+
+The test runner comes along with the main `wasm-bindgen` CLI tool. Make sure to
+replace "X.Y.Z" with the same version of `wasm-bindgen` that you already have in
+`Cargo.toml`!
+
+```shell
+cargo install wasm-bindgen-cli --vers "X.Y.Z"
+```
+
+### Configure `.cargo/config` to use the Test Runner
+
+Add this to `$MY_CRATE/.cargo/config`:
+
+```toml
+[target.wasm32-unknown-unknown]
+runner = 'wasm-bindgen-test-runner'
+```
+
+### Run the Tests
+
+Run the tests by passing `--target wasm32-unknown-unknown` to `cargo test`:
+
+```
+cargo test --target wasm32-unknown-unknown
+```