From 1421b7161b27136904d8ce870298061b6f827e08 Mon Sep 17 00:00:00 2001 From: minkimcello Date: Wed, 28 Oct 2020 16:49:48 -0400 Subject: [PATCH] Add pre-pre drafts for getting started and interactor guide --- .../docs/1-getting-started/1-installation.md | 13 ++++++ .../2-writing-your-first-test.md | 36 +++++++++++++++ .../1-interactors/1-what-are-interactors.md | 1 + .../1-interactors/2-built-in-interactors.md | 46 +++++++++++++++++++ .../1-interactors/3-custom-interactors.md | 34 ++++++++++++++ yarn.lock | 42 ++--------------- 6 files changed, 133 insertions(+), 39 deletions(-) create mode 100644 website/docs/1-getting-started/1-installation.md create mode 100644 website/docs/1-getting-started/2-writing-your-first-test.md create mode 100644 website/docs/2-guides/1-interactors/1-what-are-interactors.md create mode 100644 website/docs/2-guides/1-interactors/2-built-in-interactors.md create mode 100644 website/docs/2-guides/1-interactors/3-custom-interactors.md diff --git a/website/docs/1-getting-started/1-installation.md b/website/docs/1-getting-started/1-installation.md new file mode 100644 index 000000000..a8d39d9de --- /dev/null +++ b/website/docs/1-getting-started/1-installation.md @@ -0,0 +1,13 @@ +The `bigtest` package includes everything you need to get started sogo ahead and install BigTest to your project: +``` +$ yarn add -D bigtest +``` + +Once that's finished installing, you can run the following command: +``` +$ yarn bigtest init +``` + +This command will help generate the `bigtest.json` file for you. + +The configuration can be modified later so you can just go with its default values for now if you're not sure on some of the settings. \ No newline at end of file diff --git a/website/docs/1-getting-started/2-writing-your-first-test.md b/website/docs/1-getting-started/2-writing-your-first-test.md new file mode 100644 index 000000000..b6216d728 --- /dev/null +++ b/website/docs/1-getting-started/2-writing-your-first-test.md @@ -0,0 +1,36 @@ +To demonstrate how you can write tests, let's install the TodoMVC app from BigTest: +``` +$ yarn add -D @bigtest/todomvc +``` + +Assuming you went with the default settings for `bigtest.json`, the app command will be configured as `yarn start` as such: +```json +{ + "app": { + "command": "yarn start", + "url": "http://localhost:3000" + } +} +``` +Then go into your `package.json` file and modify the start script as `yarn bigtest-todomvc 3000`: +```json +{ + "scripts": { + "start": "yarn bigtest-todomvc 3000" + } +} +``` +Finally, let's go into the `test/` directory and create `todomvc.test.ts`: +```js +import { Heading, Page, test } from `bigtest`; + +export default test('bigtest todomvc') + .step(Page.visit('/')) + .assertion(Heading('todos').exists()); +``` + +That's it! Now you can run `yarn bigtest ci` and you should see one passing step and one passing assertion. + +_The `bigtest ci` command is meant to run in your CI workflow. It starts your app, the BigTest server, runs the tests, and closes everything on its own. The alternative is to start the server manually and then run another command to trigger the tests which is more helpful when you need to debug your app. You can find out more in the [development-workflow] section._ + +In the next section we'll be explaining what [interactors] are. \ No newline at end of file diff --git a/website/docs/2-guides/1-interactors/1-what-are-interactors.md b/website/docs/2-guides/1-interactors/1-what-are-interactors.md new file mode 100644 index 000000000..6c1033729 --- /dev/null +++ b/website/docs/2-guides/1-interactors/1-what-are-interactors.md @@ -0,0 +1 @@ +I need help here \ No newline at end of file diff --git a/website/docs/2-guides/1-interactors/2-built-in-interactors.md b/website/docs/2-guides/1-interactors/2-built-in-interactors.md new file mode 100644 index 000000000..4d954a596 --- /dev/null +++ b/website/docs/2-guides/1-interactors/2-built-in-interactors.md @@ -0,0 +1,46 @@ +Currently, these are the eight default Interactors that come with BigTest: +- [Button](link to source code) +- [CheckBox](link to source code) +- [Heading](link to source code) +- [Link](link to source code) +- [MultiSelect](link to source code) +- [RadioButton](link to source code) +- [Select](link to source code) +- [TextField](link to source code) + +In our example test in [Writing-your-first-test], we show you how you can assert against a Heading Interactor: +```js +import { Heading, Page, test } from 'bigtest'; + +export default test('bigtest todomvc') + .step(Page.visit('/')) + .assertion(Heading('todos').exists()); +``` + +But you can also use Interactors to perform actions: +```js +import { Button, Page, test, TextField } from 'bigtest'; + +export default test('some login page') + .step( + Page.visit('/login'), + TextField('Username').fillIn('Batman'), + TextField('Password').fillIn('taxevasion123'), + Button('Submit').click() + ) + .assertion(Heading('Hello Batman').exists()); +``` + +The source code for [TextField]() and [Button]() will show that its locators are `element.labels[0].textContent` and `element.textContent` respectively. So we use our locator value to refer to the correct element and invoke one of its actions. + +_In this example above we chained multiple steps together with commas. The [steps-and-assertions] section explains in-depth everything you need to know about steps and assertions._ + +But say if hypothetically you have multiple `Submit` buttons, you can narrow down and specify the element you want by using filters: +```js +.step(Button('Submit', { id: 'login-submit-button' }).click()) +``` + +Or if your button is an image and does not have text content, you can omit the locator argument and just use filters: +```js +.step(Button({ id: 'login-submit-button' }).click()) +``` \ No newline at end of file diff --git a/website/docs/2-guides/1-interactors/3-custom-interactors.md b/website/docs/2-guides/1-interactors/3-custom-interactors.md new file mode 100644 index 000000000..6344e0d88 --- /dev/null +++ b/website/docs/2-guides/1-interactors/3-custom-interactors.md @@ -0,0 +1,34 @@ +The Interactors that are offered out of the box are there for your convenience, but you can construct your own Interactors and use those instead. + +Let's go ahead and create a simple `checkbox` interactor and add it to our tutorial test: +```js +import { createInteractor, perform } from 'bigtest'; + +export const Checkbox = createInteractor('checkbox')({ + selector: 'input[type=checkbox]', + locator: (element) => element.className, + actions: { + click: perform((element) => { element.click(); }) + } +}); +``` + +And now we can import the new interactor and add it to our test: +```js +import { Button, Heading, Page, test } from 'bigtest'; +import { Checkbox } from './Checkbox'; + +export default test('bigtest todomvc') + .step(Page.visit('/')) + .assertion(Heading('todos').exists()) + .child('click checkbox', test => test + .step(Checkbox('toggle').click()) + .assertion(Button('Clear completed').exists())); +``` + +_This was just for demonstration purposes as the [checkbox](source code for checkbox) interactor from bigtest is much more extensive and it's probably not great to use the classname property as a locator._ + +Check out the API section to see the details of [createInteractor()](link). + +# questions (to be removed) +"ensure weird mutable APIs like nodelist cannot be used in filters"? \ No newline at end of file diff --git a/yarn.lock b/yarn.lock index e42dca379..704faa3ad 100644 --- a/yarn.lock +++ b/yarn.lock @@ -2132,12 +2132,7 @@ "@types/parsimmon" "^1.10.1" parsimmon "^1.13.0" -"@definitelytyped/typescript-versions@^0.0.34": - version "0.0.34" - resolved "https://registry.yarnpkg.com/@definitelytyped/typescript-versions/-/typescript-versions-0.0.34.tgz#6167363d378670ad7ef9485b7cff7d198106dcdf" - integrity sha512-7IqWcbHKYbfY8Lt7AigXDa29cbz3gynzBHMjwMUCeLnex8D682M6OW8uBLouvVHCr+YENL58tQB3dn0Zos8mFQ== - -"@definitelytyped/typescript-versions@^0.0.40", "@definitelytyped/typescript-versions@latest": +"@definitelytyped/typescript-versions@^0.0.34", "@definitelytyped/typescript-versions@^0.0.40", "@definitelytyped/typescript-versions@latest": version "0.0.40" resolved "https://registry.yarnpkg.com/@definitelytyped/typescript-versions/-/typescript-versions-0.0.40.tgz#e7888b5bd0355777f78c76c50b13b9b1aa78b18e" integrity sha512-bhgrKayF1LRHlWgvsMtH1sa/y3JzJhsEVZiZE3xdoWyv9NjZ76dpGvXTNix2dz5585KgQJLP+cKeIdZbwHnCUA== @@ -9599,7 +9594,7 @@ lodash.uniq@^4.5.0: resolved "https://registry.yarnpkg.com/lodash.uniq/-/lodash.uniq-4.5.0.tgz#d0225373aeb652adc1bc82e4945339a842754773" integrity sha1-0CJTc662Uq3BvILklFM5qEJ1R3M= -"lodash@>=3.5 <5", lodash@^4.17.11, lodash@^4.17.13, lodash@^4.17.14, lodash@^4.17.15, lodash@^4.17.4, lodash@^4.17.5: +lodash@4.17.19, "lodash@>=3.5 <5", lodash@^4.17.11, lodash@^4.17.13, lodash@^4.17.14, lodash@^4.17.15, lodash@^4.17.4, lodash@^4.17.5: version "4.17.19" resolved "https://registry.yarnpkg.com/lodash/-/lodash-4.17.19.tgz#e48ddedbe30b3321783c5b4301fbd353bc1e4a4b" integrity sha512-JNvd8XER9GQX0v2qJgsaN/mzFCNA5BRe/j8JN9d+tWyGLSodKQHKFicdwNYzWwI3wjRnaKPsGj1XkBjx/F96DQ== @@ -15298,7 +15293,7 @@ yaml@^1.7.2: resolved "https://registry.yarnpkg.com/yaml/-/yaml-1.10.0.tgz#3b593add944876077d4d683fee01081bd9fff31e" integrity sha512-yr2icI4glYaNG+KWONODapy2/jDdMSDnrONSjblABjD9B4Z5LgiircSt8m8sRZFNi08kG9Sm0uSHtEmP3zaEGg== -yargs-parser@13.1.2, yargs-parser@^13.1.2: +yargs-parser@13.1.2, yargs-parser@^10.0.0, yargs-parser@^11.1.1, yargs-parser@^13.1.2, yargs-parser@^15.0.1, yargs-parser@^18.1.1: version "13.1.2" resolved "https://registry.yarnpkg.com/yargs-parser/-/yargs-parser-13.1.2.tgz#130f09702ebaeef2650d54ce6e3e5706f7a4fb38" integrity sha512-3lbsNRf/j+A4QuSZfDRA7HRSfWrzO0YjqTJd5kjAq37Zep1CEgaYmrH9Q3GwPiB9cHyd1Y1UwggGhJGoxipbzg== @@ -15306,37 +15301,6 @@ yargs-parser@13.1.2, yargs-parser@^13.1.2: camelcase "^5.0.0" decamelize "^1.2.0" -yargs-parser@^10.0.0: - version "10.1.0" - resolved "https://registry.yarnpkg.com/yargs-parser/-/yargs-parser-10.1.0.tgz#7202265b89f7e9e9f2e5765e0fe735a905edbaa8" - integrity sha512-VCIyR1wJoEBZUqk5PA+oOBF6ypbwh5aNB3I50guxAL/quggdfs4TtNHQrSazFA3fYZ+tEqfs0zIGlv0c/rgjbQ== - dependencies: - camelcase "^4.1.0" - -yargs-parser@^11.1.1: - version "11.1.1" - resolved "https://registry.yarnpkg.com/yargs-parser/-/yargs-parser-11.1.1.tgz#879a0865973bca9f6bab5cbdf3b1c67ec7d3bcf4" - integrity sha512-C6kB/WJDiaxONLJQnF8ccx9SEeoTTLek8RVbaOIsrAUS8VrBEXfmeSnCZxygc+XC2sNMBIwOOnfcxiynjHsVSQ== - dependencies: - camelcase "^5.0.0" - decamelize "^1.2.0" - -yargs-parser@^15.0.1: - version "15.0.1" - resolved "https://registry.yarnpkg.com/yargs-parser/-/yargs-parser-15.0.1.tgz#54786af40b820dcb2fb8025b11b4d659d76323b3" - integrity sha512-0OAMV2mAZQrs3FkNpDQcBk1x5HXb8X4twADss4S0Iuk+2dGnLOE/fRHrsYm542GduMveyA77OF4wrNJuanRCWw== - dependencies: - camelcase "^5.0.0" - decamelize "^1.2.0" - -yargs-parser@^18.1.1: - version "18.1.3" - resolved "https://registry.yarnpkg.com/yargs-parser/-/yargs-parser-18.1.3.tgz#be68c4975c6b2abf469236b0c870362fab09a7b0" - integrity sha512-o50j0JeToy/4K6OZcaQmW6lyXXKhq7csREXcDwk2omFPJEwUNOVtJKvmDr9EI1fAJZUyZcRF7kxGBWmRXudrCQ== - dependencies: - camelcase "^5.0.0" - decamelize "^1.2.0" - yargs-unparser@1.6.0: version "1.6.0" resolved "https://registry.yarnpkg.com/yargs-unparser/-/yargs-unparser-1.6.0.tgz#ef25c2c769ff6bd09e4b0f9d7c605fb27846ea9f"