Aurelia's testing library enhances the developer experience by offering a Fluent API for creating test fixtures. This API provides a more readable, flexible, and chainable way to set up component tests. With the Fluent API, you can incrementally build your test fixture, making the configuration of your tests more intuitive and maintainable.

Understanding the Fluent API

The Fluent API for createFixture comprises a series of chainable methods that allow you to configure each aspect of your test fixture in a step-by-step manner. This methodical approach to building test fixtures is particularly beneficial when dealing with complex setups or when you need to express the configuration in a more descriptive way.

Legacy Approach vs. Fluent API

Previously, creating a test fixture required passing all configuration parameters to the createFixture function in a single call, which could become unwieldy as the number of configurations grew:

const { appHost, startPromise, tearDown } = await createFixture('<my-element></my-element>', class AppRoot {}, [Dependency1, Dependency2]).promise;

With the introduction of the Fluent API, you can now configure your test fixture using several self-explanatory methods, each responsible for a specific part of the setup:

const fixture = createFixture
  .component(AppRoot)
  .deps(Dependency1, Dependency2)
  .html('<my-element></my-element>');
  
const { appHost, startPromise } = await fixture.build().start();

Available Fluent API Methods

The Fluent API provides the following methods, which can be chained together to configure your test fixture:

• .component(component: any): Specifies the root component class for the test fixture.

• .deps(...dependencies: any[]): Registers additional dependencies required by the test or the components under test.

• .html(template: string | HTMLTemplateElement): Sets the HTML template for the test. This can be provided as a string literal, a tagged template literal, or an HTMLTemplateElement.

• .build(): Finalizes the configuration and builds the test fixture.

• .start(): Initializes the test fixture and returns a promise that resolves when the component is bound and attached.

Fluent API in Action: Example Test

Consider you have a MyCustomElement that relies on Dependency1 and Dependency2. The following example demonstrates how to use the Fluent API to create a test fixture for this component:

import { MyCustomElement } from './my-custom-element';
import { Dependency1, Dependency2 } from './dependencies';
import { createFixture } from '@aurelia/testing';

describe('MyCustomElement', () => {
  it('renders correctly', async () => {
    // Incrementally configure the test fixture using the Fluent API
    const fixture = createFixture
      .component(MyCustomElement)
      .deps(Dependency1, Dependency2)
      .html('<my-custom-element></my-custom-element>');

    // Build and start the fixture
    const { appHost, startPromise } = await fixture.build();

    // Await the startPromise to ensure the component is fully initialized
    await startPromise;

    // Perform assertions on appHost to verify the correct rendering of MyCustomElement
    expect(appHost.querySelector('my-custom-element')).toBeDefined();
    expect(appHost.textContent).toContain('Expected content');

    // Additional assertions and test logic...
  });
});

In this example, the Fluent API clearly outlines each step of the test fixture setup. It begins by defining the component under test, registers any dependencies, and sets the HTML template. Finally, the fixture is built and started, and the test awaits the startPromise before performing assertions.

Advantages of the Fluent API

The Fluent API offers several advantages over the traditional approach:

• Readability: The step-by-step configuration makes the test setup easier to read and understand.

• Maintainability: It's easier to update and maintain tests as configurations can be changed independently without affecting the entire setup.

• Flexibility: The API allows for dynamic adjustments to the test setup, accommodating various testing scenarios.

By employing the Fluent API, developers can write more coherent and expressive tests, enhancing the overall testing experience in Aurelia 2 applications.

Testing components in Aurelia 2 is a straightforward process thanks to the framework's design and the utilities provided by the @aurelia/testing package. This guide will walk you through the steps to test your components effectively, ensuring they work as expected within the context of a view.

In Aurelia, a component typically consists of a view (HTML) and a view model (JavaScript or TypeScript). To ensure the quality and correctness of your components, you should write tests that cover both aspects. Testing components involves checking that the view renders correctly with given data and that the view model behaves as intended when interacting with the view.

Testing Strategy

When testing components, we will focus on integration tests that involve both the view and view model. This approach allows us to verify the component as a whole, as it would function within an Aurelia application.

Example Component

For demonstration purposes, we will use a simple PersonDetail component with bindable properties name and age.

import { bindable } from 'aurelia';

export class PersonDetail {
    @bindable name: string;
    @bindable age: number;
}

<template>
    <p>Person is called ${name} and is ${age} years old.</p>
</template>

Writing the Test

We aim to test that the PersonDetail component renders the expected text when provided with name and age properties.

Test Setup

Before writing the test, ensure your environment is correctly set up for testing. Refer to the Overview section for details on how to initialize the Aurelia testing platform.

Test Implementation

Create a test file for your component, such as person-detail.spec.ts, and implement your tests using the syntax of your chosen test runner. The following example uses Jest:

import { createFixture } from '@aurelia/testing';
import { PersonDetail } from './person-detail';
import { bootstrapTestEnvironment } from './path-to-your-initialization-code';

describe('PersonDetail component', () => {
  beforeAll(() => {
    // Initialize the test environment before running the tests
    bootstrapTestEnvironment();
  });

  it('renders the name and age correctly', async () => {
    const { component, startPromise, tearDown } = createFixture(
      '<person-detail name.bind="testName" age.bind="testAge"></person-detail>',
      class App {
        testName = 'Alice';
        testAge = 30;
      },
      [PersonDetail]
    );

    await startPromise;

    expect(component.textContent).toContain('Person is called Alice and is 30 years old.');

    await tearDown();
  });

  // Additional tests...
});

In this example, createFixture is used to instantiate the component with a test context, binding name and age to specified values. We then assert that the component's text content includes the correct information. After the test completes, tearDown cleans up the component instance to avoid memory leaks and ensure test isolation.

Testing Components with Dependencies

If your component has dependencies, such as services or other custom elements, you'll need to register these within the Aurelia testing container.

Example with a Dependency

Assume PersonDetail depends on a PersonFormatter service:

import { inject } from 'aurelia';
import { PersonFormatter } from './person-formatter';

@inject(PersonFormatter)
export class PersonDetail {
    @bindable name: string;
    @bindable age: number;

    constructor(private personFormatter: PersonFormatter) {}

    get formattedDetails() {
        return this.personFormatter.format(this.name, this.age);
    }
}

To test this component, you can create a mock PersonFormatter and register it with the Aurelia container:

import { createFixture, Registration } from '@aurelia/testing';
import { PersonDetail } from './person-detail';
import { PersonFormatter } from './person-formatter';

describe('PersonDetail with PersonFormatter dependency', () => {
  it('formats the details using PersonFormatter', async () => {
    const mockPersonFormatter = {
      format: jest.fn().mockImplementation((name, age) => `Formatted: ${name}, age ${age}`),
    };

    const { component, startPromise, tearDown } = createFixture(
      '<person-detail name.bind="testName" age.bind="testAge"></person-detail>',
      class App {
        testName = 'Bob';
        testAge = 40;
      },
      [PersonDetail],
      [Registration.instance(PersonFormatter, mockPersonFormatter)]
    );

    await startPromise;

    expect(mockPersonFormatter.format).toHaveBeenCalledWith('Bob', 40);
    expect(component.textContent).toContain('Formatted: Bob, age 40');

    await tearDown();
  });
});

In the test above, we use Jest's jest.fn() to create a mock implementation of PersonFormatter. We then verify that the mock's format method is called with the correct arguments and that the component's text content includes the formatted details.

Conclusion

Testing Aurelia components involves setting up a test environment, creating fixtures, and writing assertions based on your expectations. By following these steps and best practices, you can ensure that your components are reliable and maintainable. Remember to clean up after your tests to maintain a clean test environment and to avoid any side effects between tests.

Value converters in Aurelia 2 are an essential feature that allows you to create custom logic to transform data for display in your views. When it comes to testing value converters, you should aim for a mix of unit and integration tests to ensure that they function correctly both in isolation and when integrated within a view.

Example Value Converter

Let's start with a simple value converter that transforms a string to uppercase:

import { valueConverter } from 'aurelia';

@valueConverter('toUpper')
export class ToUpper {
    toView(value: string): string {
        return value ? value.toUpperCase() : value;
    }
}

This value converter checks if the input is a string and, if so, transforms it to uppercase. If the input is null or undefined, it simply returns the input without modification.

Writing Tests for Value Converters

When testing value converters, we will create unit tests to validate the converter logic and integration tests to ensure the converter works as expected within an Aurelia view.

Setting Up the Test Environment

Before writing tests, make sure to set up the test environment as described in the Overview Section.

Test Implementation

Create a test file for your value converter, such as to-uppercase.spec.ts. Here we will write tests for both unit and integration scenarios.

import { createFixture } from '@aurelia/testing';
import { ToUpper } from './to-upper';
import { bootstrapTestEnvironment } from './path-to-your-initialization-code';

describe('ToUpper value converter', () => {
    let sut: ToUpper;

    beforeAll(() => {
        // Initialize the test environment before running the tests
        bootstrapTestEnvironment();
        sut = new ToUpper();
    });

    // Unit Tests
    it('returns null for null input', () => {
        expect(sut.toView(null)).toBeNull();
    });

    it('transforms provided string to uppercase', () => {
        expect(sut.toView('rOb wAs hErE')).toBe('ROB WAS HERE');
    });

    it('transforms provided string containing numbers to uppercase', () => {
        expect(sut.toView('rob is here 123')).toBe('ROB IS HERE 123');
    });

    // Integration Test
    it('works within a view', async () => {
        const { appHost, startPromise, tearDown } = createFixture(
            '<div>${text | toUpper}</div>',
            class App {
                text = 'rob is here 123';
            },
            [ToUpper]
        );

        await startPromise;

        expect(appHost.textContent).toBe('ROB IS HERE 123');

        await tearDown();

        expect(appHost.textContent).toBe('');
    });
});

In the unit tests, we instantiate the ToUpper value converter and directly call its toView method with different inputs to verify the output. We test with null, a valid string, and a string with numbers to cover various scenarios.

The integration test uses the createFixture function to test the value converter within an Aurelia view. We define a mock component with a text property bound to the view and apply the toUpper value converter. We then assert that the rendered text content is transformed as expected.

This method of testing can be applied to any class-based code in Aurelia 2. While the fixture bootstrap functionality is excellent for testing component output and behavior, it's not always necessary for unit testing pure code logic.

Conclusion

Testing value converters is an essential step in ensuring the reliability and robustness of your Aurelia 2 applications. By writing both unit and integration tests, you can confidently verify that your value converters perform correctly in isolation and within the context of an Aurelia view.

Testing custom attributes in Aurelia is analogous to testing components, with the primary difference being that custom attributes do not have a view template. They are, however, responsible for modifying the behavior or appearance of existing DOM elements. By leveraging the same testing techniques used for components, we can effectively validate the functionality of our custom attributes.

Example Custom Attribute

Let's consider a ColorSquareCustomAttribute that we previously created. This attribute applies a color border and sets the size of an element, resulting in a square of uniform dimensions with a colored background.

Testing the Custom Attribute

We will now write tests to ensure that the ColorSquareCustomAttribute behaves as expected when applied to an element.

Test Setup

Writing Tests

Create a test file for your custom attribute, such as color-square.spec.ts, and use the following example as a guide:

In the first test, we verify that the default size and color are applied to an element when the custom attribute is used without any bindings. In the second test, we bind the color and size properties and then change the color to ensure the colorChanged method updates the element's style as expected.

Testing Approach

As with components, we use createFixture to set up our test environment. The first argument is the HTML view where we use our custom attribute. The second argument is the view model, which can define values to bind in our view model if needed. The third argument specifies any dependencies required by our tests, such as custom elements, value converters, or attributes.

Conclusion

Testing custom attributes in Aurelia 2 is essential to ensure they correctly manipulate DOM elements as intended. By setting up a proper testing environment, creating fixtures, and writing assertions, we can confidently verify that our custom attributes perform their duties correctly. Always remember to clean up your tests to maintain a pristine testing state.

Testing in Aurelia often involves testing components that have dependencies injected into them. Using dependency injection (DI) simplifies the process of replacing these dependencies with mocks, stubs, or spies during testing. This can be particularly useful when you need to isolate the component under test from external concerns like API calls or complex logic.

Understanding Mocks, Stubs, and Spies

• Mocks are objects that replace real implementations with fake methods and properties that you define. They are useful for simulating complex behavior without relying on the actual implementation.

• Stubs are like mocks but typically focus on replacing specific methods or properties rather than entire objects. They are useful when you want to control the behavior of a dependency for a particular test case.

• Spies allow you to wrap existing methods so that you can record information about their calls, such as the number of times they were called or the arguments they received.

Using Sinon for Mocking, Stubbing, and Spying

Sinon is a popular library for creating mocks, stubs, and spies in JavaScript tests. It provides a rich API for controlling your test environment and can significantly simplify the process of testing components with dependencies.

Installing Sinon

To make use of Sinon in your Aurelia project, you need to install it along with its type definitions for TypeScript support:

Using Sinon in Your Tests

After installing Sinon, import it in your test files to access its functionality. Let's look at how to apply Sinon to mock, stub, and spy on dependencies in Aurelia components.

In this example, the MyComponent class has a dependency on IRouter and a method navigate that delegates to the router's load method.

Stubbing Individual Methods

To stub the load method of the router, use Sinon's stub method:

Mocking an Entire Dependency

When you need to replace the entire dependency, create a mock object and register it in place of the real one:

By using Registration.instance, we can ensure that any part of the application being tested will receive our mock implementation when asking for the IRouter dependency.

Spying on Methods

To observe and assert the behavior of methods, use Sinon's spies:

To test that the save method is called correctly, wrap it with a spy:

Mocking Dependencies Directly in the Constructor

Unit tests may require you to instantiate classes manually rather than using Aurelia's createFixture. In such cases, you can mock dependencies directly in the constructor:

In this test, we directly provide a mock router object when creating an instance of MyComponent. This technique is useful for more traditional unit testing where you want to test methods in isolation.

Conclusion

Mocking, stubbing, and spying are powerful techniques that can help you write more effective and isolated tests for your Aurelia components. By leveraging tools like Sinon and Aurelia's dependency injection system, you can create test environments that are both flexible and easy to control. Whether you're writing unit tests or integration tests, these methods will enable you to test your components' behavior accurately and with confidence.

Testing is integral to modern software development, ensuring that your code behaves as expected in various scenarios. Aurelia 2 facilitates testing by providing helper methods and utilities to instantiate the framework in a test environment. While Aurelia supports different test runners, such as Jest and Mocha, the core testing principles remain consistent across these tools.

Aurelia's dedicated testing library, @aurelia/testing, offers helpful functions for testing, including fixture creation methods that instantiate components with ease and handle both setup and teardown processes.

In Aurelia, testing often involves integration tests where you interact with the DOM and observe changes to content, rather than pure unit tests, which focus solely on isolated logic. It's important to test the behavior of code within the context of the view, but unit testing individual pieces of logic is also highly recommended for a comprehensive test suite.

Configuring the Test Environment

Setting up a consistent test environment is crucial to ensure tests run correctly in different environments. This setup involves initializing the Aurelia platform using the setPlatform method and configuring the Aurelia application's environment to operate within the test runner.

Initialization Code

Place the following initialization code in a shared file to be loaded by all your tests, or include it in each individual test suite:

Using the Initialization Function

By creating the bootstrapTestEnvironment function, you can easily initialize the test environment at the beginning of each test suite. This approach ensures consistency and reduces code duplication:

With your test environment configured, you can now focus on writing effective tests for your Aurelia components, ensuring that they perform as intended under various conditions.