1
0
Fork 0
mirror of https://github.com/denoland/deno.git synced 2024-12-22 15:24:46 -05:00

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.
This commit is contained in:
Luca Casonato 2020-05-10 03:09:42 +02:00 committed by GitHub
parent f6b617784f
commit 45f9b32ef0
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
17 changed files with 153 additions and 42 deletions

View file

@ -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.

View file

@ -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

View file

@ -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
```

View file

@ -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
```

View file

@ -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

View file

@ -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:

View file

@ -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
```

View file

@ -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
```

View file

@ -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
```

View file

@ -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?

View file

@ -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";

View file

@ -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

View file

@ -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.

105
docs/testing.md Normal file
View file

@ -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.

View file

@ -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",

View file

@ -6,7 +6,7 @@ and TypeScript:
<!-- prettier-ignore-start -->
<!-- prettier incorrectly moves the coming soon links to new lines -->
- [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)

View file

@ -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: