angularjs-test

:rotating_light: AngularJS test

Unit testing utility for AngularJS (1.x), heavily inspired by the wonderful Enzyme API. :heart:
Therefore, it is well suited for organisations and individuals moving from AngularJS to React. It is test framework and runner agnostic, but the examples are written using Jest syntax.

An example showing the utility in use can be found here.

Available methods:
mount
mockComponent

Returned classes:
TestElementWrapper
mock

Usage

npm install angularjs-test --save-dev

Module context

import { mount, mockComponent } from 'angularjs-test'; 

Non-module context

1. Include the script from node_modules/angularjs-test/dist/angular-test.js.
2. Use the utility from the global context under the name angularjsTest.

API

mount(template[, props]) => TestElementWrapper

Mounts the template (String) with optional props (Object) and returns a TestElementWrapper with numerous helper methods. The props are attached to the $ctrl available in the template scope.

Example

import 'angular';
import 'angular-mocks';
import { mount } from 'angularjs-test';

describe('Component under test', () => {
  const TEMPLATE = `
    <h1>{{ $ctrl.title }}</h1>
    <p>{{ $ctrl.text }}</p>
  `;

  let component;
  beforeEach(() => {
    angular.mock.module('moduleOfComponentUnderTest');
    component = mount(TEMPLATE, { title: 'A title', text: 'Some text' });
  });
});

mockComponent(name) => mock

By default, AngularJS renders the whole component tree. This function mocks a child component with name (String) in the component under test and returns a mock. The child component won't be compiled and its controller won't be invoked, enabling testing the component under test in isolation. In addition, the returned mock has methods useful for testing.

Example

import 'angular';
import 'angular-mocks';
import { mockComponent } from 'angularjs-test';

describe('Component under test', () => {
  let childComponent;
  beforeEach(() => {
    angular.mock.module('moduleOfComponentUnderTest');
    childComponent = mockComponent('child-component'); // ⇦ after module, before inject
  });
});

TestElementWrapper API

.length => Number

The number of elements in the wrapper.

Example

<ul>
  <li>1</li>
  <li>2</li>
  <li>3</li>
</ul>

it('has three list items', () => {
  expect(component.find('li').length).toBe(3);
});

.html() => String

Returns HTML of the wrapper. It should only be used for logging purposes, in tests other methods should be preferred.

Example

<h1>Some title</h1>

it('renders title as html', () => {
  expect(component.html()).toBe('<h1>Some title</h1>');
});

.text() => String

Example

<h1>Some title</h1>
<p>Some text</p>

it('has paragraph text', () => {
  expect(component.find('p').text()).toBe('Some text');
});

.hasClass(className) => Boolean

Returns whether the wrapper has a class with className (String) or not.

Example

<button class="success">Pay</button>

it('has success class', () => {
  expect(component.find('button').hasClass('success')).toBe(true);
});

it('does not have error class', () => {
  expect(component.find('button').hasClass('error')).toBe(false);
});

.exists() => Boolean

Returns whether or not the wrapper contains any elements.

Example

<button>Pay</button>

it('has button', () => {
  expect(component.find('button').exists()).toBe(true);
});

it('does not have link', () => {
  expect(component.find('a').exists()).toBe(false);
});

.find(selector) => TestElementWrapper

Returns a TestElementWrapper (for chaining) with every element matching the selector (String).

Example

<div class="left">
  <a href="https://neopets.com">Wrong</a>
  <a href="https://transferwise.com">Wrong</a>
</div>
<div class="right">
  <a href="https://neopets.com">Wrong</a>
  <a href="https://transferwise.com">Correct</a>
</div>

it('has one transferwise link with corrext text on the right', () => {
  const link = component.find('.right a[href="https://transferwise.com"]');

  expect(link.length).toBe(1);
  expect(link.text()).toBe('Correct');
});

.map(fn) => Array<Any>

Maps the nodes in the wrapper to another array using fn (Function).

Example

<ul>
  <li>One</li>
  <li>Two</li>
  <li>Three</li>
</ul>

it('has three list items with their number as a word', () => {
  const items = component.find('li');

  expect(items.map(item => item.text())).toEqual(['One', 'Two', 'Three']);
});

.props() => Object

Returns all wrapper props/attributes.

Example

<a href="https://transferwise.com" target="_blank">Send money</a>

it('has transferwise link that opens in a new tab', () => {
  expect(component.find('a').props()).toEqual({
    href: 'https://transferwise.com',
    target: '_blank',
  });
});

.prop(key) => String

Returns wrapper prop/attribute value with provided key (String).

Example

<a href="https://transferwise.com">Send money</a>

it('has transferwise link', () => {
  expect(component.find('a').prop('href')).toBe('https://transferwise.com');
});

.simulate(event[, data]) => Self

Calls an event handler on the wrapper for passed event with data (optional) and returns wrapper for chaining.

NOTE: event should be written in camelCase and without the on present in the event handler name. Currently, change and click events are supported, with change requiring an event format.

Example

<input ng-model="$ctrl.text" />
<p>{{ $ctrl.text }}</p>
<button ng-click="$ctrl.onClick({ $event: $ctrl.text })">Click me</button>

let component;
let onClick;
beforeEach(() => {
  onClick = jest.fn();
  component = mount(
    `
      <some-component
        text="$ctrl.text"
        on-click="$ctrl.onClick($event)"
      ></some-component>
    `,
    { text: 'Original text', onClick },
  );
});

it('calls click handler on button click', () => {
  const button = component.find('button');

  expect(onClick).not.toBeCalled();
  button.simulate('click');
  expect(onClick).toBeCalledWith('Original text');
});

it('changes text on input change', () => {
  const input = component.find('input');

  const text = () => component.find('p').text();

  expect(text()).toBe('Original text');
  input.simulate('change', { target: { value: 'New text' } });
  expect(text()).toBe('New text');
});

.setProps(props) => Self

Merges props (Object) with existing props and updates view to reflect them, returning itself for chaining.

Example

<h1>{{ $ctrl.title }}</h1>
<p>{{ $ctrl.text }}</p>

it('changes title and text when props change', () => {
  const component = mount(
    `
      <some-component
        title="$ctrl.title"
        text="$ctrl.text"
      ></some-component>
    `,
    { title: 'Original title', text: 'Original text' },
  );

  const title = () => component.find('h1').text();
  const text = () => component.find('p').text();

  expect(title()).toBe('Original title');
  expect(text()).toBe('Original text');
  component.setProps({ title: 'New title', text: 'New text' });
  expect(title()).toBe('New title');
  expect(text()).toBe('New text');
});

mock API

.exists() => Boolean

Returns whether or not the mocked component exists in the rendered template.

Example

let component;
beforeEach(() => {
  component = mount(`
    <button ng-click="$ctrl.show = !$ctrl.show">
      Show child
    </button>
    <child-component ng-if="$ctrl.show"></child-component>
  `);
});

it('allows toggling child component', () => {
  const button = component.find('button');

  expect(childComponent.exists()).toBe(false);
  button.simulate('click');
  expect(childComponent.exists()).toBe(true);
  button.simulate('click');
  expect(childComponent.exists()).toBe(false);
});

.props() => Object

Returns all mocked component props.

Example

let component;
beforeEach(() => {
  component = mount(`
    <div>Something else</div>
    <child-component
      some-prop="'A string'",
      some-other-prop="12345"
    ></child-component>
  `);
});

it('passes props to child component', () => {
  expect(childComponent.props()).toEqual({
    someProp: 'A string',
    someOtherProp: 12345,
  });
});

.prop(key) => Any

Returns mocked component prop value with the provided key (String).

Example

let component;
beforeEach(() => {
  component = mount(`
    <div>Something else</div>
    <child-component some-prop="'A string'"></child-component>
  `);
});

it('passes some prop to child component', () => {
  expect(childComponent.prop('someProp')).toBe('A string');
});

.simulate(event[, data]) => Self

Calls an event handler on the mocked component for passed event with data (optional) and returns mocked component for chaining.

NOTE: event should be written in camelCase and without the on present in the event handler name. So, to call onSomePropChange, .simulate('somePropChange') should be used.

Example

it('calls parent component with data when child component is called', () => {
  const onSomePropChange = jest.fn();
  mount(
    `
      <div>Something else</div>
      <child-component
        on-some-prop-change="onSomePropChange($event)"
      ></child-component>
    `,
    { onSomePropChange } // ⇦ props for component under test
  );

  expect(onSomePropChange).not.toBeCalled();
  childComponent.simulate('somePropChange', 'New value');
  expect(onSomePropChange).toBeCalledWith('New value');
});

Contributing

1. Run tests with npm run test:watch. npm test will check for package and changelog version match, ESLint and Prettier format in addition.
2. Bump version number in package.json according to semver and add an item that a release will be based on to CHANGELOG.md.
3. Submit your pull request from a feature branch and get code reviews.
4. If the pull request is approved and the CircleCI build passes, you will be able to squash/rebase and merge.
5. Code will automatically be released to GitHub and published to npm according to the version specified in the changelog and package.json.

Other

For features and bugs, feel free to add issues or contribute.

Changelog

v0.2.0

Adds mount

See README.