Poi is great. It's fantastic! It's one of the tools that were very much missing from the landscape. Now that we already have it let's explore what we can do with it. Let's get serious!
This time we're going to create a POI-based project that will support both Vue and unit testing.
First we need to have a project. A simple npm init will do. When asked to give the test command write poi test and you're done.
$ npm init
...
test command: poi test
...
Is this ok? (yes)That was easy. Now let's install the required dependencies (there are quite a few of them but we'll go through the list and I will explain what each one does):
$ npm install --save-dev poi poi-preset-karma \
webpack karma mocha chai karma-webpack karma-mocha karma-chai \
vue vue-test-utilspoi is our build system so it is obvious it needs to be installed. poi-preset-karma is a preset for poi for it to know what to do when you execute poi test. It will use karma to run the tests.
webpack and karma-webpack allow to use webpack to bundle all the files
mocha is the testing framework giving you BDD-like tests with describe and it. karma-mocha is a package that allows easy integration of Karma and Mocha.
chai is a fantastic library for writing expectations. Similarly to Mocha, karma-chai makes it easy to integrate Karma with Chai.
And last but not least we top it with some Vue sauce. vue is our beloved frontend framework and vue-test-utils is a library that aids testing.
Let's write some tests
The default folder structure assumes unit tests to be located in test/unit folder and the files to be named like something.test.js. So let's create one:
test/unit/example.test.js
it('will pass', () => {
expect(1).to.equal(1)
})Easy, right? For Poi to know what to do when we run poi test we need to use a preset. To do that we'll create a poi.config.js file like so:
module.exports = {
presets: [
require('poi-preset-karma')({
frameworks: [ 'mocha', 'chai' ]
})
]
}As you can see there we use Chai asserts. For Mocha to know about Chai we need to tell the Karma preset that both Mocha and Chai are to be used.
Now all that remains is to run the tests. There are 2 options for running:
- Run just once and finish
- Run continuously in the background and re-run tests when files change
To just run the tests and finish you issue the command
$ npm testThis works because test is a top-level npm command.
To run tests continuously with automatic re-running do this:
$ npm test -- --watchLet's decipher the bits. npm test is pretty much obvious at this point. The double-dash is a way to tell npm hey, when you run the command specified in the scripts section then add all the parameters that follow to the execution. In our case the --watch parameter enables watching changes on files and automatic re-running of all the tests.
Poi and continuous integration server
Running tests in a real browser is great because they will be testing components in their natural habitat. It poses however a difficult problem when running them on a headless continuous integration server. This is a common problem and to address that Poi has a switch that uses ChromeHeadless instead of the regular Chrome:
$ npm test -- --headlessOf course you can combine them and run headless tests in watch mode on a remote machine via SSH using Vim or Emacs as your text editor - especially if your primary work computer is running Windows and you want things to go fast(er). The possibilities are endless.
Debugging
By default tests are being executed on Google Chrome. The page you'll see contains a little DEBUG button. When you click it a new tab will open where you can set breakpoints and examine your code. One thing to note is that by default there is a limit to how long one unit test can take (2s) and you will most likely exceed that limit if you pause in a test method. Don't be alarmed by that - just re-run your tests without breakpoints and you'll see if it works or not.
Please note that the tests in debug mode won't re-run by themselves when you change things in the sources. You need to refresh the page to start a new test run. This is done so that hot-module reloading doesn't kick in in the middle of your debug session. Very convenient!
Let's go Vueing
The time has come to make a real test that uses Vuejs. So let's create one in test/unit/components/Clicker.js that will check if upon clicking on the component a custom event will be emitted:
import Vue from 'vue'
import { mount } from 'vue-test-utils'
import Clicker from '@/components/Clicker.vue'
describe('Component: Clicker', () => {
it('will emit "clicked" event when interacted with', () => {
// given
const wrapper = mount(Clicker)
// when
wrapper.vm.$el.click()
// then
expect(wrapper.emitted().clicked).to.deep.equal([ [ 'Here!' ] ])
})
})Now in the root folder let's create src/components and inside that let's create our component as a single-file component Clicker.vue:
<template>
<h1 @click="$emit('clicked', 'Here!')">Hello!</h1>
</tempalte>That's it! It is really that simple!
Post scriptum
This barely scratches the surface of what is possible with Poi but at the same time it does cover a lot of configuration that you don't need to write yourself. Just looking at the starter template for webpack-simple shows how much is being done behind the scenes.
Happy testing!
