Skip to content

Commit

Permalink
Updates testing.
Browse files Browse the repository at this point in the history
  • Loading branch information
@tcr
tcr committed Jul 18, 2018
1 parent 083513e commit 55003ee
Show file tree
Hide file tree
Showing 7 changed files with 92 additions and 45 deletions.
41 changes: 26 additions & 15 deletions docs/book/getting-started.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -134,42 +134,53 @@ <h1 class="menu-title">edit-text internals</h1>
<div id="content" class="content">
<main>
<a class="header" href="getting-started.html#getting-started" id="getting-started"><h1>Getting Started</h1></a>
<p>Before building, you'll need to install the following cargo build tools:</p>
<p>Before running with edit-text, you'll need to install the following cargo build tools globally:</p>
<pre><code>cargo install cargo-script
cargo install wasm-bindgen-cli
cargo install diesel_cli --no-default-features --features sqlite-bundled
</code></pre>
<p>Then you can clone the repository:</p>
<pre><code>git clone https://github.com/tcr/edit-text
<p>You'll also need to install the JavaScript dependencies (because cargo doesn't handle this for us). Ensure you have Node installed, then run:</p>
<pre><code>npm i --prefix ./edit-frontend
</code></pre>
<a class="header" href="getting-started.html#usage" id="usage"><h2>Usage</h2></a>
<p>To build all components of edit-text (server, client, and frontend) you can use the <code>build</code> command:</p>
<p>Clone the repository from Github:</p>
<pre><code>git clone https://github.com/tcr/edit-text
</code></pre>
<p>To build all components of edit-text (server, client, and frontend) at once, run this command from the root of the repository:</p>
<pre><code>./x.rs build
</code></pre>
<p>You can rebuild individual components with <code>server-build</code>, <code>frontend-build</code>, etc. Check <code>./x.rs help</code> for more information.</p>
<p>Build commands are executed using the <code>./x.rs</code> script. (<a href="http://timryan.org/2018/07/02/moving-from-the-shell-to-rust-with-commandspec.html">Read more.</a>) You can rebuild individual edit-text components with <code>./x.rs server-build</code>, <code>./x.rs frontend-build</code>, etc. Run <code>./x.rs help</code> for more information.</p>
<a class="header" href="getting-started.html#running-edit-text-standard" id="running-edit-text-standard"><h3>Running edit-text (standard)</h3></a>
<p>edit-text using WebAssembly is the production configuration of edit-text, where you run a server process and then one or many WebAssembly + TypeScript clients running in the browser can connect to it.</p>
<p>In your terminal session, you can run the following command to start the server (and optionally compile with release optimizations):</p>
<p>The production configuration of edit-text is a long-running server process, and one or many WebAssembly + TypeScript clients running in the browser that connect to it.</p>
<p>In your terminal session, you can run this command to start the server (and optionally compile with release optimizations):</p>
<pre><code>./x.rs server [--release]
</code></pre>
<p>Now open http://localhost:8000/ and you are brought to a welcome page to start editing!</p>
<p>After any changes are made to client or server code, run <code>./x.rs build</code> and restart the server process.</p>
<p>Now open <a href="http://localhost:8000/">http://localhost:8000/</a> and you are brought to a welcome page to start editing text!</p>
<p>Note that the server also serves WebAssembly code to the browser that contains the edit-text client. After you make changes are made to client or server code, you should re-run <code>./x.rs build</code> to recompile both and then restart the server process. (If only server changes were made, you can skip this step and just run <code>./x.rs server</code> directly.)</p>
<a class="header" href="getting-started.html#running-edit-text-with-a-client-in-proxy-mode-for-debugging" id="running-edit-text-with-a-client-in-proxy-mode-for-debugging"><h3>Running edit-text with a client in proxy mode (for debugging)</h3></a>
<p>Debugging WebAssembly code is harder (in most ways) than debugging a local Rust binary. edit-text supports running the client as an independent &quot;proxy&quot;. An edit-text server process connects to a client proxy running in another process, and communicates with browser processes using WebSockets. This client proxy is all code that would normally be cross-compiled to WebAssembly, but runs locally in your terminal and supports the same backtrace and debugging support as a local binary.</p>
<p>Debugging WebAssembly code is harder (in most ways) than debugging a local Rust binary. edit-text supports running the client as an independent &quot;proxy&quot;. An edit-text server running in one terminal connects to a client proxy running in another terminal, and communicates with frontend code running in the browser (TypeScript) over WebSockets. This client proxy is all code that would normally be cross-compiled to WebAssembly, but runs locally in your terminal and supports the same backtrace and debugging support as a local binary.</p>
<p>You'll need two terminal sessions to run in this mode. First, start the server, and specify that you want to connect to a client proxy using <code>--client-proxy</code>. Without this argument, the server will expect server connections from WebAssembly instead.</p>
<pre><code>./x.rs server --client-proxy [--release]
</code></pre>
<p>In another terminal session, you can start the proxy. (It's recommended you compile in release mode, as client code is much slower in debug mode.)</p>
<pre><code>./x.rs client-proxy [--release]
</code></pre>
<p>Then you can open http://localhost:8000/ as before in your browser, and monitor the <code>client-proxy</code> script for status of the clients that your browser is connected to.</p>
<p>Then you can open http://localhost:8000/ as before in your browser, and monitor the <code>client-proxy</code> terminal for status of the clients that your browser is connected to.</p>
<p>You will see any failures appear in the client-proxy code that would appear in the browser console when in WASM mode. If you encounter a panic or fatal error, this &quot;proxy&quot; mechanism of debugging usually gives much more information about where the error originated. Note that aside from running as a binary, there should be no differences in behavior between the client-proxy and the client in Webassembly.</p>
<a class="header" href="getting-started.html#compiling-the-frontend" id="compiling-the-frontend"><h2>Compiling the frontend</h2></a>
<p>The bundled frontend code (written in TypeScript) is tracked in git, but you can also compile it yourself. Make sure you have Node installed first, then:</p>
<pre><code>npm i --prefix ./edit-frontend
./x.rs frontend-watch
<p>If you're made changes to WebAssembly code in &quot;edit-client/&quot;, you can cross-compile the wasm binary including any <a href="https://github.com/rustwasm/wasm-bindgen">wasm-bindgen</a> with this command:</p>
<pre><code class="language-sh">./x.rs wasm-build
</code></pre>
<p>The bundled frontend code (written in TypeScript) is tracked in git and can be run immediately after cloning the repository. You can also compile it yourself. Make sure you have Node installed first, then build the frontend:</p>
<pre><code class="language-sh"># Optional: run this on first run or whenever package.json changes
npm i --prefix ./edit-frontend

./x.rs frontend-build
</code></pre>
<p>This cross-compiles all frontend code and pulls in the compiled WebAssembly binary. To watch and recompile frontend code whenever it's modified, run this command:</p>
<pre><code class="language-sh">./x.rs frontend-watch
</code></pre>
<p>This command watches the edit-frontend directory and continuously builds all frontend code, including the <code>wasm-bindgen</code> bindings.</p>
<p>This command watches the edit-frontend directory and continuously builds its after each change. Note that you may need to run <code>./x.rs wasm-build</code> as well.</p>

</main>

Expand Down
1 change: 1 addition & 0 deletions docs/book/intro-testing.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -146,6 +146,7 @@ <h1 class="menu-title">edit-text internals</h1>
Windows:
choco install selenium-gecko-driver
</code></pre>
<p>(There is only one integration test so far.) This will launch a browser session with multiple clients connecting, to ensure that synchronization code still works.</p>
<!--
<a class="header" href="intro-testing.html#oatie-testing" id="oatie-testing"><h2>Oatie testing</h2></a>
<ul>
Expand Down
42 changes: 27 additions & 15 deletions docs/book/print.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -138,42 +138,53 @@ <h1 class="menu-title">edit-text internals</h1>
<p><img src="https://user-images.githubusercontent.com/80639/42796912-9f2ae852-895a-11e8-9aae-9dede91296bf.png" alt="Preview Image" /></p>
<p>For installation instructions, please read <a href="getting-started.html"><strong>Getting Started</strong></a>.</p>
<a class="header" href="print.html#getting-started" id="getting-started"><h1>Getting Started</h1></a>
<p>Before building, you'll need to install the following cargo build tools:</p>
<p>Before running with edit-text, you'll need to install the following cargo build tools globally:</p>
<pre><code>cargo install cargo-script
cargo install wasm-bindgen-cli
cargo install diesel_cli --no-default-features --features sqlite-bundled
</code></pre>
<p>Then you can clone the repository:</p>
<pre><code>git clone https://github.com/tcr/edit-text
<p>You'll also need to install the JavaScript dependencies (because cargo doesn't handle this for us). Ensure you have Node installed, then run:</p>
<pre><code>npm i --prefix ./edit-frontend
</code></pre>
<a class="header" href="print.html#usage" id="usage"><h2>Usage</h2></a>
<p>To build all components of edit-text (server, client, and frontend) you can use the <code>build</code> command:</p>
<p>Clone the repository from Github:</p>
<pre><code>git clone https://github.com/tcr/edit-text
</code></pre>
<p>To build all components of edit-text (server, client, and frontend) at once, run this command from the root of the repository:</p>
<pre><code>./x.rs build
</code></pre>
<p>You can rebuild individual components with <code>server-build</code>, <code>frontend-build</code>, etc. Check <code>./x.rs help</code> for more information.</p>
<p>Build commands are executed using the <code>./x.rs</code> script. (<a href="http://timryan.org/2018/07/02/moving-from-the-shell-to-rust-with-commandspec.html">Read more.</a>) You can rebuild individual edit-text components with <code>./x.rs server-build</code>, <code>./x.rs frontend-build</code>, etc. Run <code>./x.rs help</code> for more information.</p>
<a class="header" href="print.html#running-edit-text-standard" id="running-edit-text-standard"><h3>Running edit-text (standard)</h3></a>
<p>edit-text using WebAssembly is the production configuration of edit-text, where you run a server process and then one or many WebAssembly + TypeScript clients running in the browser can connect to it.</p>
<p>In your terminal session, you can run the following command to start the server (and optionally compile with release optimizations):</p>
<p>The production configuration of edit-text is a long-running server process, and one or many WebAssembly + TypeScript clients running in the browser that connect to it.</p>
<p>In your terminal session, you can run this command to start the server (and optionally compile with release optimizations):</p>
<pre><code>./x.rs server [--release]
</code></pre>
<p>Now open http://localhost:8000/ and you are brought to a welcome page to start editing!</p>
<p>After any changes are made to client or server code, run <code>./x.rs build</code> and restart the server process.</p>
<p>Now open <a href="http://localhost:8000/">http://localhost:8000/</a> and you are brought to a welcome page to start editing text!</p>
<p>Note that the server also serves WebAssembly code to the browser that contains the edit-text client. After you make changes are made to client or server code, you should re-run <code>./x.rs build</code> to recompile both and then restart the server process. (If only server changes were made, you can skip this step and just run <code>./x.rs server</code> directly.)</p>
<a class="header" href="print.html#running-edit-text-with-a-client-in-proxy-mode-for-debugging" id="running-edit-text-with-a-client-in-proxy-mode-for-debugging"><h3>Running edit-text with a client in proxy mode (for debugging)</h3></a>
<p>Debugging WebAssembly code is harder (in most ways) than debugging a local Rust binary. edit-text supports running the client as an independent &quot;proxy&quot;. An edit-text server process connects to a client proxy running in another process, and communicates with browser processes using WebSockets. This client proxy is all code that would normally be cross-compiled to WebAssembly, but runs locally in your terminal and supports the same backtrace and debugging support as a local binary.</p>
<p>Debugging WebAssembly code is harder (in most ways) than debugging a local Rust binary. edit-text supports running the client as an independent &quot;proxy&quot;. An edit-text server running in one terminal connects to a client proxy running in another terminal, and communicates with frontend code running in the browser (TypeScript) over WebSockets. This client proxy is all code that would normally be cross-compiled to WebAssembly, but runs locally in your terminal and supports the same backtrace and debugging support as a local binary.</p>
<p>You'll need two terminal sessions to run in this mode. First, start the server, and specify that you want to connect to a client proxy using <code>--client-proxy</code>. Without this argument, the server will expect server connections from WebAssembly instead.</p>
<pre><code>./x.rs server --client-proxy [--release]
</code></pre>
<p>In another terminal session, you can start the proxy. (It's recommended you compile in release mode, as client code is much slower in debug mode.)</p>
<pre><code>./x.rs client-proxy [--release]
</code></pre>
<p>Then you can open http://localhost:8000/ as before in your browser, and monitor the <code>client-proxy</code> script for status of the clients that your browser is connected to.</p>
<p>Then you can open http://localhost:8000/ as before in your browser, and monitor the <code>client-proxy</code> terminal for status of the clients that your browser is connected to.</p>
<p>You will see any failures appear in the client-proxy code that would appear in the browser console when in WASM mode. If you encounter a panic or fatal error, this &quot;proxy&quot; mechanism of debugging usually gives much more information about where the error originated. Note that aside from running as a binary, there should be no differences in behavior between the client-proxy and the client in Webassembly.</p>
<a class="header" href="print.html#compiling-the-frontend" id="compiling-the-frontend"><h2>Compiling the frontend</h2></a>
<p>The bundled frontend code (written in TypeScript) is tracked in git, but you can also compile it yourself. Make sure you have Node installed first, then:</p>
<pre><code>npm i --prefix ./edit-frontend
./x.rs frontend-watch
<p>If you're made changes to WebAssembly code in &quot;edit-client/&quot;, you can cross-compile the wasm binary including any <a href="https://github.com/rustwasm/wasm-bindgen">wasm-bindgen</a> with this command:</p>
<pre><code class="language-sh">./x.rs wasm-build
</code></pre>
<p>The bundled frontend code (written in TypeScript) is tracked in git and can be run immediately after cloning the repository. You can also compile it yourself. Make sure you have Node installed first, then build the frontend:</p>
<pre><code class="language-sh"># Optional: run this on first run or whenever package.json changes
npm i --prefix ./edit-frontend

./x.rs frontend-build
</code></pre>
<p>This cross-compiles all frontend code and pulls in the compiled WebAssembly binary. To watch and recompile frontend code whenever it's modified, run this command:</p>
<pre><code class="language-sh">./x.rs frontend-watch
</code></pre>
<p>This command watches the edit-frontend directory and continuously builds all frontend code, including the <code>wasm-bindgen</code> bindings.</p>
<p>This command watches the edit-frontend directory and continuously builds its after each change. Note that you may need to run <code>./x.rs wasm-build</code> as well.</p>
<a class="header" href="print.html#system-overview" id="system-overview"><h1>System Overview</h1></a>
<p>edit-text is built from the ground up as a collaborative text editor. It uses operational transform to merge updates from multiple clients, so it requires a synchronizing server. The server is also in charge of storing page content, so that every page can be shared via its URL.</p>
<p>A client runs in a browser: text editing and synchronization code is written in Rust and cross-compiled to WebAssembly, and frontend code is written in TypeScript.</p>
Expand Down Expand Up @@ -315,6 +326,7 @@ <h1 class="menu-title">edit-text internals</h1>
Windows:
choco install selenium-gecko-driver
</code></pre>
<p>(There is only one integration test so far.) This will launch a browser session with multiple clients connecting, to ensure that synchronization code still works.</p>
<!--
<a class="header" href="print.html#oatie-testing" id="oatie-testing"><h2>Oatie testing</h2></a>
<ul>
Expand Down
2 changes: 1 addition & 1 deletion docs/book/searchindex.js
View file

Large diffs are not rendered by default.

Loading

0 comments on commit 55003ee

Please sign in to comment.