mirror of
https://github.com/leptos-rs/leptos
synced 2024-11-10 14:54:16 +00:00
Merge pull request #1529 from leptos-rs/docs-advanced-reactivity
Add advanced docs on reactive graph, and update testing docs
This commit is contained in:
Greg Johnston
GitHub
commit
aa58cedc15
3 changed files with 361 additions and 96 deletions
|
|
@ -44,4 +44,5 @@
|
|||
- [Progressive Enhancement and Graceful Degradation](./progressive_enhancement/README.md)
|
||||
- [`<ActionForm/>`s](./progressive_enhancement/action_form.md)
|
||||
- [Deployment](./deployment.md)
|
||||
- [Appendix: How Does the Reactive System Work?](./appendix_reactive_graph.md)
|
||||
- [Appendix: Optimizing WASM Binary Size](./appendix_binary_size.md)
|
||||
|
|
|
|||
243
docs/book/src/appendix_reactive_graph.md
Normal file
243
docs/book/src/appendix_reactive_graph.md
Normal file
|
|
@ -0,0 +1,243 @@
|
|||
# Appendix: How does the Reactive System Work?
|
||||
|
||||
You don’t need to know very much about how the reactive system actually works in order to use the library successfully. But it’s always useful to understand what’s going on behind the scenes once you start working with the framework at an advanced level.
|
||||
|
||||
The reactive primitives you use are divided into three sets:
|
||||
|
||||
- **Signals** (`ReadSignal`/`WriteSignal`, `RwSignal`, `Resource`, `Trigger`) Values you can actively change to trigger reactive updates.
|
||||
- **Computations** (`Memo`s) Values that depend on signals (or other computations) and derive a new reactive value through some pure computation.
|
||||
- **Effects** Observers that listen to changes in some signals or computations and run a function, causing some side effect.
|
||||
|
||||
Derived signals are a kind of non-primitve computation: as plain closures, they simply allow you to refactor some repeated signal-based computation into a reusable function that can be called in multiple places, but they are not represented in the reactive system itself.
|
||||
|
||||
All the other primitives actually exist in the reactive system as nodes in a reactive graph.
|
||||
|
||||
Most of the work of the reactive system consists of propagating changes from signals to effects, possibly through some intervening memos.
|
||||
|
||||
The assumption of the reactive system is that effects (like rendering to the DOM or making a network request) are orders of magnitude more expensive than things like updating a Rust data structure inside your app.
|
||||
|
||||
So the **primary goal** of the reactive system is to **run effects as infrequently as possible**.
|
||||
|
||||
Leptos does this through the construction of a reactive graph.
|
||||
|
||||
> Leptos’s current reactive system is based heavily on the [Reactively](https://github.com/modderme123/reactively) library for JavaScript. You can read Milo’s article “[Super-Charging Fine-Grained Reactivity](https://dev.to/modderme123/super-charging-fine-grained-reactive-performance-47ph)” for an excellent account of its algorithm, as well as fine-grained reactivity in general—including some beautiful diagrams!
|
||||
|
||||
## The Reactive Graph
|
||||
|
||||
Signals, memos, and effects all share three characteristics:
|
||||
|
||||
- **Value** They have a current value: either the signal’s value, or (for memos and effects) the value returned by the previous run, if any.
|
||||
- **Sources** Any other reactive primitives they depend on. (For signals, this is an empty set.)
|
||||
- **Subscribers** Any other reactive primitives that depend on them. (For effects, this is an empty set.)
|
||||
|
||||
In reality then, signals, memos, and effects are just conventional names for one generic concept of a “node” in a reactive graph. Signals are always “root nodes,” with no sources/parents. Effects are always “leaf nodes,” with no subscribers. Memos typically have both sources and subscribers.
|
||||
|
||||
### Simple Dependencies
|
||||
|
||||
So imagine the following code:
|
||||
|
||||
```rust
|
||||
// A
|
||||
let (name, set_name) = create_signal(cx, "Alice");
|
||||
|
||||
// B
|
||||
let name_upper = create_memo(cx, move |_| name.with(|n| n.to_uppercase()));
|
||||
|
||||
// C
|
||||
create_effect(cx, move |_| {
|
||||
log!("{}", name_upper());
|
||||
});
|
||||
|
||||
set_name("Bob");
|
||||
```
|
||||
|
||||
You can easily imagine the reactive graph here: `name` is the only signal/origin node, the `create_effect` is the only effect/terminal node, and there’s one intervening memo.
|
||||
|
||||
```
|
||||
A (name)
|
||||
|
|
||||
B (name_upper)
|
||||
|
|
||||
C (the effect)
|
||||
```
|
||||
|
||||
### Splitting Branches
|
||||
|
||||
Let’s make it a little more complex.
|
||||
|
||||
```rust
|
||||
// A
|
||||
let (name, set_name) = create_signal(cx, "Alice");
|
||||
|
||||
// B
|
||||
let name_upper = create_memo(cx, move |_| name.with(|n| n.to_uppercase()));
|
||||
|
||||
// C
|
||||
let name_len = create_memo(cx, move |_| name.len());
|
||||
|
||||
// D
|
||||
create_effect(cx, move |_| {
|
||||
log!("len = {}", name_len());
|
||||
});
|
||||
|
||||
// E
|
||||
create_effect(cx, move |_| {
|
||||
log!("name = {}", name_upper());
|
||||
});
|
||||
```
|
||||
|
||||
This is also pretty straightforward: a signal source signal (`name`/`A`) divides into two parallel tracks: `name_upper`/`B` and `name_len`/`C`, each of which has an effect that depends on it.
|
||||
|
||||
```
|
||||
__A__
|
||||
| |
|
||||
B C
|
||||
| |
|
||||
D E
|
||||
```
|
||||
|
||||
Now let’s update the signal.
|
||||
|
||||
```rust
|
||||
set_name("Bob");
|
||||
```
|
||||
|
||||
We immediately log
|
||||
|
||||
```
|
||||
len = 3
|
||||
name = BOB
|
||||
```
|
||||
|
||||
Let’s do it again.
|
||||
|
||||
```rust
|
||||
set_name("Tim");
|
||||
```
|
||||
|
||||
The log should shows
|
||||
|
||||
```
|
||||
name = TIM
|
||||
```
|
||||
|
||||
`len = 3` does not log again.
|
||||
|
||||
Remember: the goal of the reactive system is to run effects as infrequently as possible. Changing `name` from `"Bob"` to `"Tim"` will cause each of the memos to re-run. But they will only notify their subscribers if their value has actually changed. `"BOB"` and `"TIM"` are different, so that effect runs again. But both names have the length `3`, so they do not run again.
|
||||
|
||||
### Reuniting Branches
|
||||
|
||||
One more example, of what’s sometimes called **the diamond problem**.
|
||||
|
||||
```rust
|
||||
// A
|
||||
let (name, set_name) = create_signal(cx, "Alice");
|
||||
|
||||
// B
|
||||
let name_upper = create_memo(cx, move |_| name.with(|n| n.to_uppercase()));
|
||||
|
||||
// C
|
||||
let name_len = create_memo(cx, move |_| name.len());
|
||||
|
||||
// D
|
||||
create_effect(cx, move |_| {
|
||||
log!("{} is {} characters long", name_upper(), name_len());
|
||||
});
|
||||
```
|
||||
|
||||
What does the graph look like for this?
|
||||
|
||||
```
|
||||
__A__
|
||||
| |
|
||||
B C
|
||||
| |
|
||||
|__D__|
|
||||
```
|
||||
|
||||
You can see why it's called the “diamond problem.” If I’d connected the nodes with straight lines instead of bad ASCII art, it would form a diamond: two memos, each of which depend on a signal, which feed into the same effect.
|
||||
|
||||
A naive, push-based reactive implementation would cause this effect to run twice, which would be bad. (Remember, our goal is to run effects as infrequently as we can.) For example, you could implement a reactive system such that signals and memos immediately propagate their changes all the way down the graph, through each dependency, essentially traversing the graph depth-first. In other words, updating `A` would notify `B`, which would notify `D`; then `A` would notify `C`, which would notify `D` again. This is both inefficient (`D` runs twice) and glitchy (`D` actually runs with the incorrect value for the second memo during its first run.)
|
||||
|
||||
## Solving the Diamond Problem
|
||||
|
||||
Any reactive implementation worth its salt is dedicated to solving this issue. There are a number of different approaches (again, [see Milo’s article](https://dev.to/modderme123/super-charging-fine-grained-reactive-performance-47ph) for an excellent overview).
|
||||
|
||||
Here’s how ours works, in brief.
|
||||
|
||||
A reactive node is always in one of three states:
|
||||
|
||||
- `Clean`: it is known not to have changed
|
||||
- `Check`: it is possible it has changed
|
||||
- `Dirty`: it has definitely changed
|
||||
|
||||
Updating a signal `Dirty` marks that signal `Dirty`, and marks all its descendants `Check`, recursively. Any of its descendants that are effects are added to a queue to be re-run.
|
||||
|
||||
```
|
||||
____A (DIRTY)___
|
||||
| |
|
||||
B (CHECK) C (CHECK)
|
||||
| |
|
||||
|____D (CHECK)__|
|
||||
```
|
||||
|
||||
Now those effects are run. (All of the effects will be marked `Check` at this point.) Before re-running its computation, the effect checks its parents to see if they are dirty. So
|
||||
|
||||
- So `D` goes to `B` and checks if it is `Dirty`.
|
||||
- But `B` is also marked `Check`. So `B` does the same thing:
|
||||
- `B` goes to `A`, and finds that it is `Dirty`.
|
||||
- This means `B` needs to re-run, because one of its sources has changed.
|
||||
- `B` re-runs, generating a new value, and marks itself `Clean`
|
||||
- Because `B` is a memo, it then checks its prior value against the new value.
|
||||
- If they are the same, `B` returns "no change." Otherwise, it returns "yes, I changed."
|
||||
- If `B` returned “yes, I changed,” `D` knows that it definitely needs to run and re-runs immediately before checking any other sources.
|
||||
- If `B` returned “no, I didn’t change,” `D` continues on to check `C` (see process above for `B`.)
|
||||
- If neither `B` nor `C` has changed, the effect does not need to re-run.
|
||||
- If either `B` or `C` did change, the effect now re-runs.
|
||||
|
||||
Because the effect is only marked `Check` once and only queued once, it only runs once.
|
||||
|
||||
If the naive version was a “push-based” reactive system, simply pushing reactive changes all the way down the graph and therefore running the effect twice, this version could be called “push-pull.” It pushes the `Check` status all the way down the graph, but then “pulls” its way back up. In fact, for large graphs it may end up bouncing back up and down and left and right on the graph as it tries to determine exactly which nodes need to re-run.
|
||||
|
||||
**Note this important trade-off**: Push-based reactivity propagates signal changes more quickly, at the expense of over-re-running memos and effects. Remember: the reactive system is designed to minimize how often you re-run effects, on the (accurate) assumption that side effects are orders of magnitude more expensive than this kind of cache-friendly graph traversal happening entirely inside the library’s Rust code. The measurement of a good reactive system is not how quickly it propagates changes, but how quickly it propagates changes _without over-notifying_.
|
||||
|
||||
## Memos vs. Signals
|
||||
|
||||
Note that signals always notify their children; i.e., a signal is always marked `Dirty` when it updates, even if its new value is the same as the old value. Otherwise, we’d have to require `PartialEq` on signals, and this is actually quite an expensive check on some types. (For example, add an unnecessary equality check to something like `some_vec_signal.update(|n| n.pop())` when it’s clear that it has in fact changed.)
|
||||
|
||||
Memos, on the other hand, check whether they change before notifying their children. They only run their calculation once, no matter how many times you `.get()` the result, but they run whenever their signal sources change. This means that if the memo’s computation is _very_ expensive, you may actually want to memoize its inputs as well, so that the memo only re-calculates when it is sure its inputs have changed.
|
||||
|
||||
## Memos vs. Derived Signals
|
||||
|
||||
All of this is cool, and memos are pretty great. But most actual applications have reactive graphs that are quite shallow and quite wide: you might have 100 source signals and 500 effects, but no memos or, in rare case, three or four memos between the signal and the effect. Memos are extremely good at what they do: limiting how often they notify their subscribers that they have changed. But as this description of the reactive system should show, they come with overhead in two forms:
|
||||
|
||||
1. A `PartialEq` check, which may or may not be expensive.
|
||||
2. Added memory cost of storing another node in the reactive system.
|
||||
3. Added computational cost of reactive graph traversal.
|
||||
|
||||
In cases in which the computation itself is cheaper than this reactive work, you should avoid “over-wrapping” with memos and simply use derived signals. Here’s a great example in which you should never use a memo:
|
||||
|
||||
```rust
|
||||
let (a, set_a) = create_signal(cx, 1);
|
||||
// none of these make sense as memos
|
||||
let b = move || a() + 2;
|
||||
let c = move || b() % 2 == 0;
|
||||
let d = move || if c() { "even" } else { "odd" };
|
||||
|
||||
set_a(2);
|
||||
set_a(3);
|
||||
set_a(5);
|
||||
```
|
||||
|
||||
Even though memoizing would technically save an extra calculation of `d` between setting `a` to `3` and `5`, these calculations are themselves cheaper than the reactive algorithm.
|
||||
|
||||
At the very most, you might consider memoizing the final node before running some expensive side effect:
|
||||
|
||||
```rust
|
||||
let text = create_memo(cx, move |_| {
|
||||
d()
|
||||
});
|
||||
create_effect(cx, move |_| {
|
||||
engrave_text_into_bar_of_gold(&text());
|
||||
});
|
||||
```
|
||||
|
|
@ -53,128 +53,149 @@ pub fn TodoApp(cx: Scope) -> impl IntoView {
|
|||
In general, the less of your logic is wrapped into your components themselves, the
|
||||
more idiomatic your code will feel and the easier it will be to test.
|
||||
|
||||
## 2. Test components with `wasm-bindgen-test`
|
||||
## 2. Test components with end-to-end (`e2e`) testing
|
||||
|
||||
[`wasm-bindgen-test`](https://crates.io/crates/wasm-bindgen-test) is a great utility
|
||||
for integrating or end-to-end testing WebAssembly apps in a headless browser.
|
||||
Our [`examples`](https://github.com/leptos-rs/leptos/tree/main/examples) directory has several examples with extensive end-to-end testing, using different testing tools.
|
||||
|
||||
To use this testing utility, you need to add `wasm-bindgen-test` to your `Cargo.toml`:
|
||||
The easiest way to see how to use these is to take a look at the test examples themselves:
|
||||
|
||||
```toml
|
||||
[dev-dependencies]
|
||||
wasm-bindgen-test = "0.3.0"
|
||||
```
|
||||
### `wasm-bindgen-test` with [`counter`](https://github.com/leptos-rs/leptos/blob/main/examples/counter/tests/web.rs)
|
||||
|
||||
You should create tests in a separate `tests` directory. You can then run your tests in the browser of your choice:
|
||||
This is a fairly simple manual testing setup that uses the [`wasm-pack test`](https://rustwasm.github.io/wasm-pack/book/commands/test.html) command.
|
||||
|
||||
```bash
|
||||
wasm-pack test --firefox
|
||||
```
|
||||
|
||||
> To see the full setup, check out the tests for the [`counter`](https://github.com/leptos-rs/leptos/tree/main/examples/counter) example.
|
||||
|
||||
### Writing Your Tests
|
||||
|
||||
Most tests will involve some combination of vanilla DOM manipulation and comparison to a `view`. For example, here’s a test [for the
|
||||
`counter` example](https://github.com/leptos-rs/leptos/blob/main/examples/counter/tests/web.rs).
|
||||
|
||||
First, we set up the testing environment.
|
||||
#### Sample Test
|
||||
|
||||
```rust
|
||||
use wasm_bindgen_test::*;
|
||||
use counter::*;
|
||||
use leptos::*;
|
||||
use web_sys::HtmlElement;
|
||||
|
||||
// tell the test runner to run tests in the browser
|
||||
wasm_bindgen_test_configure!(run_in_browser);
|
||||
```
|
||||
|
||||
I’m going to create a simpler wrapper for each test case, and mount it there.
|
||||
This makes it easy to encapsulate the test results.
|
||||
|
||||
```rust
|
||||
// like marking a regular test with #[test]
|
||||
#[wasm_bindgen_test]
|
||||
fn clear() {
|
||||
let document = leptos::document();
|
||||
let test_wrapper = document.create_element("section").unwrap();
|
||||
document.body().unwrap().append_child(&test_wrapper);
|
||||
let _ = document.body().unwrap().append_child(&test_wrapper);
|
||||
|
||||
// start by rendering our counter and mounting it to the DOM
|
||||
// note that we start at the initial value of 10
|
||||
mount_to(
|
||||
test_wrapper.clone().unchecked_into(),
|
||||
|cx| view! { cx, <SimpleCounter initial_value=10 step=1/> },
|
||||
);
|
||||
|
||||
let div = test_wrapper.query_selector("div").unwrap().unwrap();
|
||||
let clear = test_wrapper
|
||||
.query_selector("button")
|
||||
.unwrap()
|
||||
.unwrap()
|
||||
.unchecked_into::<web_sys::HtmlElement>();
|
||||
|
||||
clear.click();
|
||||
|
||||
assert_eq!(
|
||||
div.outer_html(),
|
||||
/* HTML expected */
|
||||
);
|
||||
```
|
||||
|
||||
### [`wasm-bindgen-test` with `counters_stable`](https://github.com/leptos-rs/leptos/tree/main/examples/counters_stable/tests/web)
|
||||
|
||||
This more developed test suite uses a system of fixtures to refactor the manual DOM manipulation of the `counter` tests and easily test a wide range of cases.
|
||||
|
||||
#### Sample Test
|
||||
|
||||
```rust
|
||||
use super::*;
|
||||
use crate::counters_page as ui;
|
||||
use pretty_assertions::assert_eq;
|
||||
|
||||
#[wasm_bindgen_test]
|
||||
fn should_increase_the_total_count() {
|
||||
// Given
|
||||
ui::view_counters();
|
||||
ui::add_counter();
|
||||
|
||||
// When
|
||||
ui::increment_counter(1);
|
||||
ui::increment_counter(1);
|
||||
ui::increment_counter(1);
|
||||
|
||||
// Then
|
||||
assert_eq!(ui::total(), 3);
|
||||
}
|
||||
```
|
||||
|
||||
We’ll use some manual DOM operations to grab the `<div>` that wraps
|
||||
the whole component, as well as the `clear` button.
|
||||
### [Playwright with `counters_stable`](https://github.com/leptos-rs/leptos/tree/main/examples/counters_stable/e2e)
|
||||
|
||||
```rust
|
||||
// now we extract the buttons by iterating over the DOM
|
||||
// this would be easier if they had IDs
|
||||
let div = test_wrapper.query_selector("div").unwrap().unwrap();
|
||||
let clear = test_wrapper
|
||||
.query_selector("button")
|
||||
.unwrap()
|
||||
.unwrap()
|
||||
.unchecked_into::<web_sys::HtmlElement>();
|
||||
```
|
||||
These tests use the common JavaScript testing tool Playwright to run end-to-end tests on the same example, using a library and testing approach familiar to may who have done frontend development before.
|
||||
|
||||
Now we can use ordinary DOM APIs to simulate user interaction.
|
||||
#### Sample Test
|
||||
|
||||
```rust
|
||||
// now let's click the `clear` button
|
||||
clear.click();
|
||||
```
|
||||
```js
|
||||
import { test, expect } from "@playwright/test";
|
||||
import { CountersPage } from "./fixtures/counters_page";
|
||||
|
||||
You can test individual DOM element attributes or text node values. Sometimes
|
||||
I like to test the whole view at once. We can do this by testing the element’s
|
||||
`outerHTML` against our expectations.
|
||||
test.describe("Increment Count", () => {
|
||||
test("should increase the total count", async ({ page }) => {
|
||||
const ui = new CountersPage(page);
|
||||
await ui.goto();
|
||||
await ui.addCounter();
|
||||
|
||||
```rust
|
||||
assert_eq!(
|
||||
div.outer_html(),
|
||||
// here we spawn a mini reactive system to render the test case
|
||||
run_scope(create_runtime(), |cx| {
|
||||
// it's as if we're creating it with a value of 0, right?
|
||||
let (value, set_value) = create_signal(cx, 0);
|
||||
await ui.incrementCount();
|
||||
await ui.incrementCount();
|
||||
await ui.incrementCount();
|
||||
|
||||
// we can remove the event listeners because they're not rendered to HTML
|
||||
view! { cx,
|
||||
<div>
|
||||
<button>"Clear"</button>
|
||||
<button>"-1"</button>
|
||||
<span>"Value: " {value} "!"</span>
|
||||
<button>"+1"</button>
|
||||
</div>
|
||||
}
|
||||
// the view returned an HtmlElement<Div>, which is a smart pointer for
|
||||
// a DOM element. So we can still just call .outer_html()
|
||||
.outer_html()
|
||||
})
|
||||
);
|
||||
```
|
||||
|
||||
That test involved us manually replicating the `view` that’s inside the component.
|
||||
There's actually an easier way to do this... We can just test against a `<SimpleCounter/>`
|
||||
with the initial value `0`. This is where our wrapping element comes in: I’ll just test
|
||||
the wrapper’s `innerHTML` against another comparison case.
|
||||
|
||||
```rust
|
||||
assert_eq!(test_wrapper.inner_html(), {
|
||||
let comparison_wrapper = document.create_element("section").unwrap();
|
||||
leptos::mount_to(
|
||||
comparison_wrapper.clone().unchecked_into(),
|
||||
|cx| view! { cx, <SimpleCounter initial_value=0 step=1/>},
|
||||
);
|
||||
comparison_wrapper.inner_html()
|
||||
await expect(ui.total).toHaveText("3");
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
This is only a very limited introduction to testing. But I hope it’s useful as you begin to build applications.
|
||||
### [Gherkin/Cucumber Tests with `todo_app_sqlite`](https://github.com/leptos-rs/leptos/blob/main/examples/todo_app_sqlite/e2e/README.md)
|
||||
|
||||
> For more, see [the testing section of the `wasm-bindgen` guide](https://rustwasm.github.io/wasm-bindgen/wasm-bindgen-test/index.html#testing-on-wasm32-unknown-unknown-with-wasm-bindgen-test).
|
||||
You can integrate any testing tool you’d like into this flow. This example uses Cucumber, a testing framework based on natural language.
|
||||
|
||||
```
|
||||
@add_todo
|
||||
Feature: Add Todo
|
||||
|
||||
Background:
|
||||
Given I see the app
|
||||
|
||||
@add_todo-see
|
||||
Scenario: Should see the todo
|
||||
Given I set the todo as Buy Bread
|
||||
When I click the Add button
|
||||
Then I see the todo named Buy Bread
|
||||
|
||||
# @allow.skipped
|
||||
@add_todo-style
|
||||
Scenario: Should see the pending todo
|
||||
When I add a todo as Buy Oranges
|
||||
Then I see the pending todo
|
||||
```
|
||||
|
||||
The definitions for these actions are defined in Rust code.
|
||||
|
||||
```rust
|
||||
use crate::fixtures::{action, world::AppWorld};
|
||||
use anyhow::{Ok, Result};
|
||||
use cucumber::{given, when};
|
||||
|
||||
#[given("I see the app")]
|
||||
#[when("I open the app")]
|
||||
async fn i_open_the_app(world: &mut AppWorld) -> Result<()> {
|
||||
let client = &world.client;
|
||||
action::goto_path(client, "").await?;
|
||||
|
||||
Ok(())
|
||||
}
|
||||
|
||||
#[given(regex = "^I add a todo as (.*)$")]
|
||||
#[when(regex = "^I add a todo as (.*)$")]
|
||||
async fn i_add_a_todo_titled(world: &mut AppWorld, text: String) -> Result<()> {
|
||||
let client = &world.client;
|
||||
action::add_todo(client, text.as_str()).await?;
|
||||
|
||||
Ok(())
|
||||
}
|
||||
|
||||
// etc.
|
||||
```
|
||||
|
||||
### Learning More
|
||||
|
||||
Feel free to check out the CI setup in the Leptos repo to learn more about how to use these tools in your own application. All of these testing methods are run regularly against actual Leptos example apps.
|
||||
|
|
|
|||
Loading…
Reference in a new issue