From 45f9b32ef0416e0477e9f5335df49ca3cccdb6eb Mon Sep 17 00:00:00 2001 From: Luca Casonato Date: Sun, 10 May 2020 03:09:42 +0200 Subject: [PATCH] Docs for deno test + minor other changes (#5185) * Added fs events example. * Added docs for `deno test`. * Renamed file server example. * Unified markdown code types. * Removed plugin topics from TOC. * Fixed links. --- docs/contributing.md | 2 +- docs/contributing/building_from_source.md | 6 +- docs/contributing/development_tools.md | 8 +- .../{fileserver.md => file_server.md} | 2 +- docs/examples/file_system_events.md | 18 +++ docs/examples/tcp_echo.md | 2 +- docs/examples/unix_cat.md | 2 +- docs/getting_started/first_steps.md | 12 +- docs/getting_started/typescript.md | 2 +- docs/linking_to_external_code.md | 4 +- docs/runtime/program_lifecycle.md | 2 +- docs/runtime/stability.md | 2 +- docs/runtime/workers.md | 3 +- docs/testing.md | 105 ++++++++++++++++++ docs/toc.json | 18 +-- docs/tools.md | 2 +- docs/tools/script_installer.md | 5 +- 17 files changed, 153 insertions(+), 42 deletions(-) rename docs/examples/{fileserver.md => file_server.md} (97%) create mode 100644 docs/examples/file_system_events.md create mode 100644 docs/testing.md diff --git a/docs/contributing.md b/docs/contributing.md index df2d1de24a..f83756e9b6 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,6 +1,6 @@ # Contributing -- Read the [style guide](contributing/style_guide.md). +- Read the [style guide](./contributing/style_guide.md). - Please don't make [the benchmarks](https://deno.land/benchmarks.html) worse. diff --git a/docs/contributing/building_from_source.md b/docs/contributing/building_from_source.md index 62bbf23034..381ad7b039 100644 --- a/docs/contributing/building_from_source.md +++ b/docs/contributing/building_from_source.md @@ -8,7 +8,7 @@ Deno you can download a prebuilt executable (more information in the Clone on Linux or Mac: -```bash +```shell git clone --recurse-submodules https://github.com/denoland/deno.git ``` @@ -18,7 +18,7 @@ Extra steps for Windows users: (otherwise symlinks would require administrator privileges). 2. Make sure you are using git version 2.19.2.windows.1 or newer. 3. Set `core.symlinks=true` before the checkout: - ```bash + ```shell git config --global core.symlinks true git clone --recurse-submodules https://github.com/denoland/deno.git ``` @@ -77,7 +77,7 @@ about the V8 build. Build with Cargo: -```bash +```shell # Build: cargo build -vv diff --git a/docs/contributing/development_tools.md b/docs/contributing/development_tools.md index 35bd5a5fbd..b8aa9505f9 100644 --- a/docs/contributing/development_tools.md +++ b/docs/contributing/development_tools.md @@ -4,7 +4,7 @@ Test `deno`: -```bash +```shell # Run the whole suite: cargo test @@ -14,7 +14,7 @@ cargo test js_unit_tests Test `std/`: -```bash +```shell cargo test std_tests ``` @@ -22,13 +22,13 @@ cargo test std_tests Lint the code: -```bash +```shell ./tools/lint.py ``` Format the code: -```bash +```shell ./tools/format.py ``` diff --git a/docs/examples/fileserver.md b/docs/examples/file_server.md similarity index 97% rename from docs/examples/fileserver.md rename to docs/examples/file_server.md index 3ed9d90e70..9fbe27bd37 100644 --- a/docs/examples/fileserver.md +++ b/docs/examples/file_server.md @@ -2,7 +2,7 @@ This one serves a local directory in HTTP. -```bash +```shell deno install --allow-net --allow-read https://deno.land/std/http/file_server.ts ``` diff --git a/docs/examples/file_system_events.md b/docs/examples/file_system_events.md new file mode 100644 index 0000000000..2abebc33e8 --- /dev/null +++ b/docs/examples/file_system_events.md @@ -0,0 +1,18 @@ +### File system events + +To poll for file system events: + +```ts +const watcher = Deno.watchFs("/"); +for await (const event of watcher) { + console.log(">>>> event", event); + // { kind: "create", paths: [ "/foo.txt" ] } +} +``` + +Note that the exact ordering of the events can vary between operating systems. +This feature uses different syscalls depending on the platform: + +- Linux: inotify +- macOS: FSEvents +- Windows: ReadDirectoryChangesW diff --git a/docs/examples/tcp_echo.md b/docs/examples/tcp_echo.md index d7c2e9e722..360c5faccd 100644 --- a/docs/examples/tcp_echo.md +++ b/docs/examples/tcp_echo.md @@ -25,7 +25,7 @@ For security reasons, Deno does not allow programs to access the network without explicit permission. To allow accessing the network, use a command-line flag: ```shell -$ deno run --allow-net https://deno.land/std/examples/echo_server.ts +deno run --allow-net https://deno.land/std/examples/echo_server.ts ``` To test it, try sending data to it with netcat: diff --git a/docs/examples/unix_cat.md b/docs/examples/unix_cat.md index 7534ef0d0f..ca85ea3259 100644 --- a/docs/examples/unix_cat.md +++ b/docs/examples/unix_cat.md @@ -20,5 +20,5 @@ I/O streams in Deno. Try the program: ```shell -$ deno run --allow-read https://deno.land/std/examples/cat.ts /etc/passwd +deno run --allow-read https://deno.land/std/examples/cat.ts /etc/passwd ``` diff --git a/docs/getting_started/first_steps.md b/docs/getting_started/first_steps.md index 74dbae1b42..8c9e4ea0ab 100644 --- a/docs/getting_started/first_steps.md +++ b/docs/getting_started/first_steps.md @@ -17,13 +17,13 @@ and use modern features wherever possible. Because of this browser compatibility a simple `Hello World` program is actually no different to one you can run in the browser: -```typescript +```ts console.log("Welcome to Deno 🦕"); ``` Try the program: -```bash +```shell deno run https://deno.land/std/examples/welcome.ts ``` @@ -37,7 +37,7 @@ Just like in the browser you can use the web standard [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) API to make HTTP calls: -```typescript +```ts const url = Deno.args[0]; const res = await fetch(url); @@ -60,7 +60,7 @@ Lets walk through what this application does: Try it out: -```bash +```shell deno run https://deno.land/std/examples/curl.ts https://example.com ``` @@ -71,7 +71,7 @@ programs the permission to do certain 'privileged' actions like network access. Try it out again with the correct permission flag: -```bash +```shell deno run --allow-net=example.com https://deno.land/std/examples/curl.ts https://example.com ``` @@ -103,7 +103,7 @@ I/O streams in Deno. Try the program: -```bash +```shell deno run --allow-read https://deno.land/std/examples/cat.ts /etc/passwd ``` diff --git a/docs/getting_started/typescript.md b/docs/getting_started/typescript.md index ebe1e5e708..35a513b37d 100644 --- a/docs/getting_started/typescript.md +++ b/docs/getting_started/typescript.md @@ -100,7 +100,7 @@ be provided to Deno on program execution. You need to explicitly tell Deno where to look for this configuration by setting the `-c` argument when executing your application. -```bash +```shell deno run -c tsconfig.json mod.ts ``` diff --git a/docs/linking_to_external_code.md b/docs/linking_to_external_code.md index 5484a78065..e03bfdfee8 100644 --- a/docs/linking_to_external_code.md +++ b/docs/linking_to_external_code.md @@ -1,6 +1,6 @@ # Linking to third party code -In the [Getting Started](../getting_started) section, we saw that Deno could +In the [Getting Started](./getting_started.md) section, we saw that Deno could execute scripts from URLs. Like browser JavaScript, Deno can import libraries directly from URLs. This example uses a URL to import an assertion library: @@ -52,7 +52,7 @@ specifying that path as the `$DENO_DIR` environmental variable at runtime. By using a lock file (using the `--lock` command line flag) you can ensure you're running the code you expect to be. You can learn more about this -[here](./integrity_checking). +[here](./linking_to_external_code/integrity_checking.md). ### How do you import to a specific version? diff --git a/docs/runtime/program_lifecycle.md b/docs/runtime/program_lifecycle.md index dda8a06f92..c7c3c46a39 100644 --- a/docs/runtime/program_lifecycle.md +++ b/docs/runtime/program_lifecycle.md @@ -8,7 +8,7 @@ Listener for `load` events can be asynchronous and will be awaited. Listener for Example: -```typescript +```ts // main.ts import "./imported.ts"; diff --git a/docs/runtime/stability.md b/docs/runtime/stability.md index a158638b98..cd7c270392 100644 --- a/docs/runtime/stability.md +++ b/docs/runtime/stability.md @@ -10,7 +10,7 @@ are not ready because they are still in draft phase are locked behind the - It enables the use of unstable APIs during runtime. - It adds the [`lib.deno.unstable.d.ts`](https://github.com/denoland/deno/blob/master/cli/js/lib.deno.unstable.d.ts) - file to the list of TypeScript definitions that are used for typechecking. + file to the list of TypeScript definitions that are used for type checking. This includes the output of `deno types`. You should be aware that unstable APIs have probably **not undergone a security diff --git a/docs/runtime/workers.md b/docs/runtime/workers.md index 0418f057e0..3c39d2cee7 100644 --- a/docs/runtime/workers.md +++ b/docs/runtime/workers.md @@ -20,7 +20,8 @@ new Worker("./worker.js", { type: "classic" }); ### Using Deno in worker -**UNSTABLE**: This feature is unstable and requires `--unstable` flag +> This is an unstable Deno feature. Learn more about +> [unstable features](./stability.md). By default `Deno` namespace is not available in worker scope. diff --git a/docs/testing.md b/docs/testing.md new file mode 100644 index 0000000000..d6f59e3ec3 --- /dev/null +++ b/docs/testing.md @@ -0,0 +1,105 @@ +# Testing + +Deno has a built-in test runner that you can use for testing JavaScript or +TypeScript code. + +## Writing tests + +To define a test you need to call `Deno.test` with a name and function to be +tested: + +```ts +Deno.test("hello world", () => { + const x = 1 + 2; + if (x !== 3) { + throw Error("x should be equal to 3"); + } +}); +``` + +There are some useful assertion utilities at https://deno.land/std/testing to +make testing easier: + +```ts +import { assertEquals } from "https://deno.land/std/testing/asserts.ts"; + +Deno.test("hello world", () => { + const x = 1 + 2; + assertEquals(x, 3); +}); +``` + +### Async functions + +You can also test asynchronous code by passing a test function that returns a +promise. For this you can use the `async` keyword when defining a function: + +```ts +Deno.test("async hello world", async () => { + const x = 1 + 2; + + // await some async task + await delay(100); + + if (x !== 3) { + throw Error("x should be equal to 3"); + } +}); +``` + +### Resource and async op sanitizers + +Certain actions in Deno create resources in the resource table +([learn more here](./contributing/architecture.md)). These resources should be +closed after you are done using them. + +For each test definition the test runner checks that all resources created in +this test have been closed. This is to prevent resource 'leaks'. This is enabled +by default for all tests, but can be disabled by setting the `sanitizeResources` +boolean to false in the test definition. + +The same is true for async operation like interacting with the filesystem. The +test runner checks that each operation you start in the test is completed before +the end of the test. This is enabled by default for all tests, but can be +disabled by setting the `sanitizeOps` boolean to false in the test definition. + +```ts +Deno.test({ + name: "leaky test", + fn() { + Deno.open("hello.txt"); + }, + sanitizeResources: false, + sanitizeOps: false, +}); +``` + +### Ignoring tests + +Sometimes you want to ignore tests based on some sort of condition (for example +you only want a test to run on Windows). For this you can use the `ignore` +boolean in the test definition. If it is set to true the test will be skipped. + +```ts +Deno.test({ + name: "do macOS feature", + ignore: Deno.build.os !== "darwin", + fn() { + doMacOSFeature(); + }, +}); +``` + +## Running tests + +To run the test, call `deno test` with the file that contains your test +function: + +```shell +deno test my_test.ts +``` + +You can also omit the file name, in which case all tests in the current +directory (recursively) that match the glob `{*_,}test.{js,ts,jsx,tsx}` will be +run. If you pass a directory, all files in the directory that match this glob +will be run. diff --git a/docs/toc.json b/docs/toc.json index 061ba66f67..5369a00652 100644 --- a/docs/toc.json +++ b/docs/toc.json @@ -17,7 +17,7 @@ "name": "The Runtime", "children": { "stability": "Stability", - "program_lifecycle": "Program Lifecycle", + "program_lifecycle": "Program lifecycle", "compiler_apis": "Compiler APIs", "workers": "Workers" } @@ -32,19 +32,7 @@ } }, "testing": { - "name": "Testing", - "children": { - "writing": "Writing tests", - "running": "Running tests" - } - }, - "plugins": { - "name": "Plugins", - "children": { - "how_do_plugins_work": "How do plugins work?", - "creating_plugins": "Creating plugins", - "using_plugins": "Using plugins" - } + "name": "Testing" }, "tools": { "name": "Tools", @@ -73,7 +61,7 @@ "name": "Examples", "children": { "unix_cat": "Unix cat program", - "fileserver": "File server", + "file_server": "File server", "tcp_echo": "TCP echo server", "subprocess": "Creating a subprocess", "permissions": "Inspecting and revoking permissions", diff --git a/docs/tools.md b/docs/tools.md index f3dae49e8d..904bf027f6 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -6,7 +6,7 @@ and TypeScript: -- [test runner (`deno test`)](../testing) +- [test runner (`deno test`)](./testing.md) - [code formatter (`deno fmt`)](./tools/formatter.md) - [bundler (`deno bundle`)](./tools/bundler.md) - [debugger (`--debug`)](./tools/debugger.md) diff --git a/docs/tools/script_installer.md b/docs/tools/script_installer.md index ffd920cf3c..6badd6436b 100644 --- a/docs/tools/script_installer.md +++ b/docs/tools/script_installer.md @@ -61,9 +61,8 @@ $ deno install --allow-net --allow-read https://deno.land/std/http/file_server.t The above command creates an executable called `file_server` that runs with write and read permissions and binds to port 8080. -For good practice, use the -[`import.meta.main`](#testing-if-current-file-is-the-main-program) idiom to -specify the entry point in an executable script. +For good practice, use the [`import.meta.main`](../examples/testing_if_main.md) +idiom to specify the entry point in an executable script. Example: