# quasar-testing

**Repository Path**: lemon_engine/quasar-testing

## Basic Information

- **Project Name**: quasar-testing
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2021-04-29
- **Last Updated**: 2021-05-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p style="text-align:center">
    <img src="testing_header.png" />
</p>

# **`@quasar/testing`**

This is the monorepo for integrating the test-runner of your choice into your Quasar app.

You can install multiple pre-rigged testing harnesses (test runners) to your Quasar application, each one will:

- install the harness NPM package into your project;
- scaffold necessary configuration files;
- add script commands, if you so choose, which expose some functionality of the respective harness.

> App Extensions (such as these testing harnesses) only work with Quasar CLI, not with Vue CLI, nor by directly installing packages via a package manager as npm or yarn. Use `quasar ext add ...` or the installation step won't be executed and configuration files won't be copied over.

Testing is not in and of itself hard. The most complicated part is setting up the testing harness. The trick lies in knowing what to test. If you are new to testing, it is absolutely imperative that you familiarize yourself with some of the concepts and patterns. There are some links for further reading at the end of this document page.

The Test Driven Design approach will help you to write better (and fewer) tests. Even though it may seem like it slows you down to some degree, this habit pays its dividends on the long term drastically reducing the number of public bugs and the project maintenance effort. Think of tests like insurance for your code that always pays out. On the other hand, not everything is worth being tested, or is worth being tested only at an higher level (eg. using an E2E tests instead of unit tests).

<div class="text-center">
  <div class="h3">REMEMBER</div>
  <div class="h5">Test the functionality, not the function</div>
</div>

## Table of contents

- [Donations](#donations)
- [Installation](#installation)
- [Removal](#removal)
- [Reset](#reset)
- [Upgrade](#upgrade)
- Provided App Extensions
  - [Testing Harnesses Manager](packages/testing/README.md)
  - Unit testing
    - [Jest](packages/unit-jest/README.md)
    - [Ava](#ava) (**not up to date**)
  - E2E testing
    - [Cypress](packages/e2e-cypress/README.md)
    - [WebDriver.io](#webdriverio-wdio) (**not up to date, WIP**)
  - [Quality Auditing](#quality-auditing) (**not up to date**)
- [Roadmap](#roadmap)
- [Contributing](#contributing)
- [License](#license)

## Donations

The Quasar team spend a considerabile amount of time studying, coding and maintaining App Extensions which save literally thousands of developers hours, days or weeks of work.

Does your business or personal projects depend on these App Extensions? How much time did we save you until now? Consider [donating](https://github.com/sponsors/rstoenescu) to help us maintain them and allow us to create new ones!

## Installation

You can add test harnesses:

- in a centralized way via the [Testing Harnesses Manager](packages/testing/README.md);
- using an "a-la-carte" approach, checking each harness documentation.

You can add multiple harnesses and even use them into your continuous integration pipelines.

## Removal

You can remove a testing harness running:

```shell
$ quasar ext remove @quasar/testing-unit-jest
```

This will remove the associated NPM package and run the Quasar App Extensions uninstall hook.
If not done into the AE uninstall hook, the removal won't delete test or configuration files.

## Reset

If you mess up your configuration and need to reset, or just want to check out if there has been any changes into new versions configuration, you should run:

```shell
$ quasar ext add @quasar/testing-unit-jest
```

Be careful though, this will overwrite ALL existing files (including configurations) if you allow it to. Make sure to have some kind of version control in place before proceeding. This operation will also upgrade the NPM package and its dependencies.

To prevent installing new or updated dependencies, you should run:

```shell
$ quasar ext invoke @quasar/testing-unit-jest
```

## Upgrade

You can upgrade a testing harness and its dependencies by updating its related NPM package.

```
$ yarn add -D @quasar/quasar-app-extension-testing-unit-jest
```

This won't change existing test or configuration files.

### Upgrade to a new major version with NPM

When upgrading between major versions, since there are major changes, we suggest you to remove and re-add the AE, to obtain lastest configuration files too.
Ensure your source control is clean before proceeding, then answer (y) and "Overwrite all" when prompted to overwrite existing files and individually `git diff` all changes manually to check out which changes you want to keep and which you want to revert.

```shell
$ quasar ext remove @quasar/testing-unit-jest
$ quasar ext add @quasar/testing-unit-jest
```

## Testing Harnesses Manager

[Check out Testing Harnesses Manager AE documentation](packages/testing/README.md)

## Unit Testing

### [Jest](https://jestjs.io/)

[Check out Jest AE documentation](packages/unit-jest/README.md)

### [AVA](https://github.com/avajs/ava)

```shell
$ quasar ext add @quasar/testing-unit-ava
```

We have included:

- a configuration file `ava.config.js`
- `/test/ava/setup.js`
- `babel.config.js` file
- a `quasar` scaffolding helper
- a 'validity' test that makes sure quasar is initiatable

We have included the optional ability to place your test code inside your vue files, should you choose to do so. It will be rendered by webpack HMR. To run these tests, run `$ quasar test --unit ava --dev`.

```
<test lang="ava">
  /* your complete test file here */
</test>
```

> You may notice that your IDE doesn't know how to parse the test block, so go into the `<test/>` block, press `<alt> + <enter>`, select 'inject language or reference' and select `javascript`. This will grant `<test/>` blocks autocomplete.

## e2e Testing

We recommend testing webapps with Cypress if you target Chrome-based browsers (Chrome, Edge, Electron) or Firefox - but if you want to test Safari, IE or Cordova apps, then you should consider using webdriver.io.

### [Cypress](https://www.cypress.io/)

[Check out Cypress AE documentation](packages/e2e-cypress/README.md)

### [WebDriver.io](https://webdriver.io/) (wdio)

```shell
$ quasar ext add @quasar/testing-e2e-wdio
$ yarn selenium:install && selenium:start
```

**WIP** - please help battle test this harness.
FYI: we're using webdriver 4.0 for the moment because wdio requires it. If you need to use webdriver 5, please get in touch and we can create another app-extension.

Prior Work:
https://github.com/fansanelli/quasar-webdriver/blob
https://github.com/NodeJunkie/quasar-webdriver/tree/feat/BackportToQuasar%231

### Quality Auditing

```shell
$ quasar ext add @quasar/testing-quality
```

Auditing the quality of your app is something you want to do before you go in production. Depending on your perspective, quality can mean many things. So we have put together a few tools that we think can help you have a qualitatively better project.

The `Lighthouse` tool can help you identify issues with your PWA app, but only if you serve the built version of your project. If you use it a lot, consider installing it globally.

`Snyk` is a tool for identifying node modules that have security implications. Running this regularly will keep you alerted to issues that may be stemming from repositories you use.

`Node License Finder (nlf)` is a free tool you can use to catalog all the licenses of the hundreds of open-source projects you are using in your project.

## Contributing

Setup the monorepo locally:

- fork this repository on GitHub
- clone it locally (`git clone https://github.com/<YOUR-GITHUB-HANDLE>/quasar-testing.git`)
- move into the monorepo folder (`cd quasar-testing`)
- install dependencies (`yarn install`)
- move into the folder of the harness you want to work on (`cd packages/e2e-cypress`)
- if the harness require a build step (eg. Jest AE), run the build command (`yarn build`)

Create a project where to test the harnesses, **OUTSIDE `quasar-testing` folder**:

- open another terminal
- create a new clean Quasar project (`quasar create <my-test-project>`)
- locally install the harness NPM package (`yarn add -D ../quasar-testing/packages/e2e-cypress`)
- invoke the App Extension (`quasar ext invoke @quasar/testing-e2e-cypress`)

Read the [App Extensions development docs](https://quasar.dev/app-extensions/development-guide/introduction).

---

The packages in this repo follow the following naming convention:

- @quasar/app-extension-testing-unit-\*
- @quasar/app-extension-testing-e2e-\*
- @quasar/app-extension-testing-quality

Quasar internally maps extensions (pruning "app-extension-") when running `quasar ext ...` commands, eg. `ava` test-runner AE id would be `@quasar/testing-unit-ava`.

There will be more and more test-harnesses coming as time permits. If you would like to help us add official harnesses, please open an issue or get in touch on Quasar Discord server #testing channel.

Avoid opening PRs without getting in touch with us, as we may refuse to merge integrations we cannot commit to maintain.
In these cases, we encourage you to publish and maintain the new integration AE on your own. We'll try to help you getting started and link your integration on this README :)

## Roadmap

Test harnesses currently verified to have valid "integration" are checked off in the following list.
We won't commit to any deadline for integrations of new harnesses.

### UNIT

- [x] [ava](https://github.com/avajs/ava)
- [ ] [jasmine 3](https://jasmine.github.io/)
- [x] [jest 26](https://facebook.github.io/jest/)
- [ ] [tap](https://github.com/tapjs/node-tap)
- [ ] [tape](https://github.com/substack/tape)
- [ ] [mocha-webpack](https://github.com/zinserjan/mocha-webpack)

### E2E

- [ ] [appium](https://github.com/appium/appium) (cordova)
- [x] [cypress](https://github.com/cypress-io/cypress)
- [ ] [karma](https://github.com/karma-runner/karma)
- [ ] [nightwatch](http://nightwatchjs.org/)
- [ ] [polly.js](https://github.com/Netflix/pollyjs)
- [ ] [spectron](https://github.com/electron/spectron) (electron)
- [ ] [testcafe](https://github.com/DevExpress/testcafe)
- [ ] [testee](https://github.com/bitovi/testee)
- [x] [webdriver.io](http://webdriver.io/) (wdio - multi tenant) - Not ready for production

### QUALITY

- [x] [lighthouse 3.0](https://github.com/GoogleChrome/lighthouse)
- [x] [snyk](https://snyk.io/test)
- [x] [nlf](https://github.com/iandotkelly/nlf) (Node license finder)
- [ ] [import-cost](https://github.com/wix/import-cost/tree/master/packages/import-cost) (custom)
- [ ] [bundlesize](https://github.com/siddharthkp/bundlesize) (custom)
- [ ] [webpagetest](https://www.webpagetest.org/)

### UTILS

- [ ] [jest-codemods](https://www.npmjs.com/package/jest-codemods)
- [ ] [ava-codemods](https://github.com/avajs/ava-codemods) (tape=>ava)

## Further Reading

### Books

- [Testing Vue.js Applications](https://www.manning.com/books/testing-vue-js-applications) by Edd Yerburgh, the author of the `@vue/test-utils` repo
- [Free Vue Testing Handbook](https://lmiller1990.github.io/vue-testing-handbook/)

### Tutorials

- [Introduction to TDD](https://www.computer.org/csdl/magazine/so/2007/03/s3024/13rRUygT7kK)
- [Overview of JavaScript testing 2020](https://medium.com/welldone-software/an-overview-of-javascript-testing-7ce7298b9870)
- [Unit Testing Vue Router with Jest](https://medium.com/js-dojo/unit-testing-vue-router-1d091241312)
- [Jest tests debugging](https://artsy.github.io/blog/2018/08/24/How-to-debug-jest-tests/)

### Documentation

- [@vue/test-utils](https://vue-test-utils.vuejs.org)
- [jest 24](https://facebook.github.io/jest/)
- [cypress](https://docs.cypress.io/guides/core-concepts/introduction-to-cypress.html#Cypress-Is-Simple)
- [lighthouse](https://developers.google.com/web/tools/lighthouse/#cli)
- [snyk](https://snyk.io/test)
- [nlf](https://www.npmjs.com/package/nlf)
- [chai](http://www.chaijs.com/)
- [istanbul](https://istanbul.js.org/)

## Contributing

Contributions to this repository are highly desirable. Before you make a PR, please open an issue, create a fork and PR. See the [Contribution Guidelines](./.github/CONTRIBUTING.md) for more details. Please note: Project coordination takes place on the [Discord server](https://discord.gg/5TDhbDg).

## Contributors

- [nothingismagick](https://github.com/nothingismagick)
- [nklayman](https://github.com/nklayman)
- [Allan Gaunt](https://github.com/webnoob)
- [andreiTn](https://github.com/andreiTn)
- [fansanelli](https://github.com/fansanelli)
- mgibson91
- eugene
- bloo_df
- PhearZero

## Special Thanks

Denjell would like to give a special shout out to all of the people who helped test the testing framework during the transition from 0.17 to 1.0

## License

MIT ©2018 - present - D.C. Thompson & Razvan Stoenescu

All Icons © the respective owners