Skip to content
This repository has been archived by the owner on Jan 5, 2023. It is now read-only.

Commit

Permalink
feat(improve-docs)
Browse files Browse the repository at this point in the history
  • Loading branch information
HugoDF committed May 3, 2020
1 parent d0c2313 commit b75e647
Show file tree
Hide file tree
Showing 3 changed files with 131 additions and 20 deletions.
32 changes: 16 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Utilities for testing Alpine.js components.

**This library allows you to quickly and easily write tests for Alpine.js applications via Node.js using any testing library.**
**This library allows you to quickly and easily write tests for Alpine.js applications via Node.js using _any testing library_.**

This project is not officially affiliated with Alpine.js, it's maintained by community members. For any feedback, questions or issues, please create [issues](https://github.com/HugoDF/alpine-test-utils/issues) and [pull requests](https://github.com/HugoDF/alpine-test-utils/blob/master/README.md#contributing) or merely upvote or comment on existing issues or pull requests.

Expand All @@ -12,7 +12,8 @@ This project is not officially affiliated with Alpine.js, it's maintained by com
- [Installation](#installation)
- [Prerequisites](#prerequisites)
- [Install Package](#install-package)
- [Quick Start, Create a Draft](#quick-start-create-a-draft)
- [Peer Dependencies](#peer-dependencies)
- [Quick Start, Write your first test](#quick-start-write-your-first-test)
- [Roadmap](#roadmap)
- [Contributing](#contributing)
- [Requirements](#requirements)
Expand Down Expand Up @@ -42,28 +43,30 @@ You may also use [yarn](https://yarnpkg.com/en/) to install.
yarn add --dev alpine-test-utils
```

> **Note**: if you're using Alpine.js from CDN you will also need to install it using npm or Yarn
## Peer Dependencies

**IMPORTANT**: If you're loading Alpine.js from CDN (using a `script` tag) you'll need to install `alpinejs` in order to use `alpine-test-utils`. It should be the same version as the version of Alpine.js you are loading from CDN. using.

```sh
npm install --save alpinejs
npm install --save-dev alpinejs
# or for Yarn users
yarn add alpinejs
yarn add --dev alpinejs
```

<a name="quick-start"></a>
# Quick Start, Create a Draft
# Quick Start, Write your first test

Here's an example to render an Alpine.js component that's situated in the `test.html` file:

```js
import {load, render} from 'alpine-test-utils';
import {render} from 'alpine-test-utils';

test('render and override x-data', () => {
test('test foo component', () => {
const componentHtml = `<div x-data="{foo: 'hello'}">
<span x-text="foo"></span>
</div>`
const component = render(componentHtml, { foo: 'world' });
expect(component.querySelector('span').innerText).toEqual('world');
const component = render(componentHtml);
expect(component.querySelector('span').innerText).toEqual('bar');
});
```

Expand All @@ -85,16 +88,13 @@ If you are interested in the future direction of this project, please take a loo

1. Clone the repository
2. Run `yarn` or `npm install` installs all required dependencies.
3. Run `yarn build` to build from TypeScript to common JavaScript distribution formats.
4. Run `yarn test` to run all tests :D.
3. Run `yarn test` to run all tests :D.

## npm scripts

> Equivalent `npm run <script>` should also work
- `yarn test` run tests against **built output** with [ava](https://github.com/avajs/ava). **Important**: runs against build output so run `yarn build` beforehand.
- `yarn build` run build from TypeScript to UMD, CJS, ESM with [microbundle](https://github.com/developit/microbundle)
- `yarn watch` runs build in watch mode with [microbundle](https://github.com/developit/microbundle)
- `yarn test` run tests with [ava](https://github.com/avajs/ava).
- `yarn lint` will lint all of the files with [xo](https://github.com/xojs/xo)
- `yarn format` will run lint with `--fix` option on all the examples files (and tests).
- `yarn release`, run clean, production build and release with `np`.
Expand All @@ -109,9 +109,9 @@ This package is maintained by Hugo from [Code with Hugo](https://codewithhugo.co
Special thanks to:

- The developers behind
- [Alpine.js](https://github.com/alpinejs/alpine)
- [ava](https://avajs.dev)
- [esm](https://github.com/standard-things/esm#readme)
- [microbundle](https://github.com/developit/microbundle#readme)
- [np](https://github.com/sindresorhus/np#readme)
- [xo](https://github.com/xojs/xo#readme)

Expand Down
109 changes: 105 additions & 4 deletions USE_CASES.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,109 @@
This documentation provides examples for specific use cases in Node.js. Please [open an issue](https://github.com/HugoDF/microbundle-ts-pkg/issues) or make a pull request for any other use cases you would like us to document here. Thank you!
This documentation provides examples for specific use cases in Node.js. Please [open an issue](https://github.com/HugoDF/alpine-test-utils/issues) or make a pull request for any other use cases you would like us to document here. Thank you!


## Table of contents/resource list
## Table of contents

## Resource 1
- [Clicking a button to toggle visibility](#clicking-a-button-to-toggle-visibility)
- [Intercepting `fetch` calls & waiting for re-renders](#intercepting-fetch-calls--waiting-for-re-renders)
- [Loading & rendering a PHP template that injects into x-data](#loading--rendering-a-php-template-that-injects-into-x-data)
- [Loading & rendering an HTML file and running it](#loading--rendering-an-html-file-and-running-it)

Use cases for the resource
### Clicking a button to toggle visibility

```js
import test from 'ava';
import {render} from 'alpine-test-utils';

test('use-case - clicking a button to toggle visibility', async (t) => {
const component = render(`<div x-data="{ isOpen: false }">
<button @click="isOpen = !isOpen"></button>
<span x-show="isOpen"></span>
</div>`);

t.is(component.querySelector('span').style.display, 'none');
component.querySelector('button').click();
await component.$nextTick();
t.is(component.querySelector('span').style.display, '');
});
```

### Intercepting `fetch` calls & waiting for re-renders

```js
import test from 'ava';
import {render, setGlobal} from 'alpine-test-utils';

test('use-case - intercepting fetch calls', async (t) => {
setGlobal({
fetch: () =>
Promise.resolve({
json: () => Promise.resolve(['data-1', 'data-2'])
})
});
const component = render(`<div
x-data="{ data: [] }"
x-init="fetch().then(r => r.json()).then(d => {
data = d;
})"
>
<template x-for="d in data" :key="d">
<span data-testid="text-el" x-text="d"></span>
</template>
</div>`);
// Flushes the Promises
await component.$nextTick();
t.deepEqual(component.$data.data, ['data-1', 'data-2']);
// Lets the re-render run
await component.$nextTick();
const textNodes = component.querySelectorAll('[data-testid=text-el]');
t.is(textNodes.length, 2);
t.is(textNodes[0].innerText, 'data-1');
t.is(textNodes[1].innerText, 'data-2');
});
```

### Loading & rendering a PHP template that injects into x-data

```js
import test from 'ava';
import path from 'path';
import {load, loadSync, render} from 'alpine-test-utils';

test('use-case - PHP template - async', async (t) => {
const markup = await load(path.join(__dirname, '../fixtures/template.php'));
// Overwrite `x-data` since it's set by a PHP expression
const component = render(markup, {
foo: 'baz'
});
t.is(component.querySelector('span').innerText, 'baz');
});

test('use-case - PHP template - sync', (t) => {
const markup = loadSync(path.join(__dirname, '../fixtures/template.php'));
// Overwrite `x-data` since it's set by a PHP expression
const component = render(markup, {
foo: 'baz'
});
t.is(component.querySelector('span').innerText, 'baz');
});
```

### Loading & rendering an HTML file and running it

```js
import test from 'ava';
import path from 'path';
import {load, loadSync, render} from 'alpine-test-utils';

test('use-case - load from HTML file - async', async (t) => {
const markup = await load(path.join(__dirname, '../fixtures/template.html'));
const component = render(markup);
t.is(component.querySelector('span').innerText, 'bar');
});

test('use-case - load from HTML file - sync', (t) => {
const markup = loadSync(path.join(__dirname, '../fixtures/template.html'));
const component = render(markup);
t.is(component.querySelector('span').innerText, 'bar');
});
```
10 changes: 10 additions & 0 deletions tests/example.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
import test from 'ava';
import {render} from '../src/main';

test('test foo component', (t) => {
const componentHtml = `<div x-data="{foo: 'bar'}">
<span x-text="foo"></span>
</div>`;
const component = render(componentHtml);
t.is(component.querySelector('span').innerText, 'bar');
});

0 comments on commit b75e647

Please sign in to comment.