README
ember-hook
Way to go! You just completed a full and rigorous suite of acceptance tests for your Ember app! But wait, what is this? Your designers have overhauled the site, and now you need to update all your tests to reflect new class names? Well, #@!%!!!
Enter ember-hook
. Rather than coupling your tests to fickle class names, it lets you use stable data attributes. Better yet, these attributes only appear when you're running your tests, keeping your source trim and simple in production.
Installation
ember install ember-hook
Usage
Use the hook
helper to define your data attribute:
<div class="arnt-i-pretty" data-test={{hook "foo"}}>bar</div>
Or the hook
attribute in your component:
export default Ember.Component.extend({
hook: 'foo'
});
Then in your tests:
import { hook, $hook } from 'ember-hook';
. . . .
test('my hooks work', function(assert) {
assert.equal($hook('foo').text().trim(), 'bar'); // works
assert.equal(find(hook('foo')).text().trim(), 'bar'); // also works
});
hook
returns a string such as [data-test="foo"]
, while $hook
returns an actual jquery object.
Qualifiers
Class names aren't the only fickle thing about the DOM. The DOM itself is fickle. You might be tempted to scour a parent for a child element like this:
find(`${hook('item')}:nth(2)`);
But if that child element moves somewhere else in the DOM, you're in trouble. So ember-hook
provides some tools for decoupling your hooks from the DOM structure itself. Just pass some named params into the hook
helper:
{{#each parentArray as |childArray containerIndex|}}
{{#each childArray as |item index|}}
<div data-test={{hook "item" index=index containerIndex=containerIndex}}>{{item}}</div>
{{!-- or --}}
{{my-component hook="item" hookQualifiers=(hash index=index containerIndex=containerIndex)}}
{{/each}}
{{/each}}
And then in your tests:
$hook('item', { index: 2, containerIndex: someVariable }); // grabs a very specific 'item'
$hook('item', { containerIndex: 5 }); // grabs all 'items' contained by the 5th parent
$hook('item'); // grabs all items
Extending
Sometimes, you may want to extend hookQualifiers
from a parent when passing it to a child. For instance, in the case above, the outer {{#each}}
might be in one component, and the inner {{#each}}
might be in a child.
In that case, the child can extend the parent's hookQualifiers
adding on the index
property. This is assuming that the child was given a hookQualifiers
property
{{#each childArray as |item index|}}
<div data-test={{hook "item" (extend hookQualifiers index=index)}}>{{item}}</div>
{{!-- or --}}
{{my-component hook="item" hookQualifiers=(extend hookQualifiers index=index)}}
{{/each}}
In order for this to work, you'll need an extend
helper, which doesn't exist natively in Ember
but is very simple to add to your project:
import Ember from 'ember';
const { Helper, assign } = Ember;
export function extend ([original], newProps) {
return assign({}, original, newProps);
}
export default Helper.helper(extend);
initialize
ember-hook
works out-of-the-box with acceptance tests, but component integration tests present a problem: they do not run initializers. This includes the ember-hook
initializer that allows you to use the hook
attribute on a component. To fix this, you'll need to manually run the initializer in your component test:
import { initialize } from 'ember-hook';
moduleForComponent('my component', 'Integration | Component | my component', {
integration: true,
beforeEach() {
initialize();
}
});
Changing Component Hook
If there's a conflict with the property hook
on your components, you can change the property name in your config/environment
file:
// config/environment.js
var ENV ={
emberHook: {
hookName: 'customHookName'
}
}
Changing Component Hook Qualifier
If there's a conflict with the property hookQualifiers
on your components, you can change the property name in your config/environment
file:
// config/environment.js
var ENV ={
emberHook: {
hookQualifierName: 'customHookQualifierName'
}
}
Changing the Delimiter
ember-hook
delimits qualifiers by appending the string '&^%^&' to each. If this happens to conflict with something your code, you can change it in the config as well:
// config/environment.js
var ENV ={
emberHook: {
delimiter: '¯\_(0)_/¯'
}
}
Enabling ember-hook outside of the test environment
ember-hook
by default is enabled when the environment is test
or development
. If you need to force ember-hook to be enabled in other environments, or always on, you can use enabled
.
// config/environment.js
var ENV ={
emberHook: {
enabled: true
}
}
// config/environment.js
module.exports = function(environment) {
var ENV ={
emberHook: {
// only enable in test or production builds
enabled: environment === 'production'
}
}
// ...
}