Skip to content

MIGRATION.md

Latest commit

 

History

History
200 lines (131 loc) · 6.17 KB

MIGRATION.md

File metadata and controls

200 lines (131 loc) · 6.17 KB

Spectator v3.x to v4 - Migration Guide

Spectator 4 has arrived! While this is a major version change (from 3.x to 4.x), we've tried our best to keep breaking changes to a minimum. However, in order to deliver new features and to keep our API as clean as possible, there are some changes required.

Why upgrading? 🤔

Short answer: to benefit from fixes and new features, you should upgrade to the newest version of Spectator. Spectator 4 has much to offer:

  • Routing support
  • Improved support for Directives
  • Cleaner and more consistent API
  • Improved factories for Services and HTTP
  • Angular 8 / Jasmine 3 support
  • Global query support

Please head to the CHANGELOG for a complete list of changes.

Migration Script

For some of the changes, we created a migration script. After installing Spectator v4, just run:

$ node node_modules/@ngneat/spectator/migrate.js

This will apply some of the migration changes to your *.spec.ts files.

BREAKING CHANGES ❌

Let's first discuss what we changed or removed. You will need to make these changes in order to use Spectator 4.

Moved from @netbasal/spectator to @ngneat/spectator

We moved this library from @netbasal to the @ngneat scope. Please update your imports accordingly.

Spectator overrides

We changed the signature of the factories Spectator and SpectatorWithHost (now called SpectatorHost) to accept an object with override options.

❌ Before:

const spectator = createComponent({ foo: 'bar' }, false);
const host = createHost('<some-component></some-component>', false, { foo: 'bar' });

✅ After:

const spectator = createComponent({
  props: { foo: 'bar' },
  detectChanges: false
});
const spectator = createHost('<some-component></some-component>', {
  props: { foo: 'bar' },
  detectChanges: false
});

Removed matchers

The following matchers were deprecated in v3 and have been removed in v4:

  • ❌ toHaveAttr (in favour of ✅ toHaveAttribute)
  • ❌ toHaveProp (in favour of ✅ toHaveProperty)

Removed spectator.getDirectiveInstance()

❌ Before:

const fooDirective = spectator.getDirectiveInstance(FooDirective);

✅ After:

const fooDirective = spectator.queryHost(FooDirective);
const fooDirective = spectator.queryHost('.some-element', { read: FooDirective });

Removed spectator.$$('.some-selector')

For global queries, we removed the spectator.$$('.some-selector') method.

Please use spectator.query('.some-selector', { root: true }) instead.

Removed patchElementFocus method.

Removed MockComponent and MockDirective

The MockComponent and MockDirective were deprecated in v3 and have been removed in v4. Please use the corresponding mock functions from the ng-mocks library.

Component Providers

In Spectator v3.x, due to a bug, all components default providers were removed by default.

As of Spectator 4, the component providers are only replaced if you explicitly specify them using componentProviders.

DEPRECATIONS ⚠️

Let's now discuss what we have deprecated, but not completely removed. Before Spectator releases v5, you will need to remove and replace all use of the following functionality:

Factory names

We changed the names of the following factories functions and their corresponding interfaces.

Before:

Function name: Returning a factory for:
createTestComponentFactory ⚠️ Spectator
createHostComponentFactory ⚠️ SpectatorWithHost ⚠️
createHTTPFactory ⚠️ SpectatorHTTP ⚠️

After:

Function name: Returning a factory for:
createComponentFactory ✅ Spectator
createHostFactory ✅ SpectatorHost ✅
createHttpFactory ✅ SpectatorHttp ✅

We did this in order to be consistent with the new factories we introduced:

Function name: Returning a factory for:
createDirectiveFactory 😎 SpectatorDirective 😎
createRoutingFactory 😎 SpectatorRouting 😎
createServiceFactory 😎 SpectatorService 😎

Deprecated SpectatorHTTP in favour of SpectatorHttp

The new SpectatorHttp has a more consistent API and supports more options, like mocks, entry components, etc.

We also deprecated the dataService property in favour of service;

⚠️ Before:

const http = createHTTPFactory(SomeService);

it('...', () => {
  const { dataService, get } = http();
  dataService.foo();
});

✅ After:

const createHttp = createHttpFactory(SomeService);
let spectator: SpectatorHttp<SomeService>;

beforeEach(() => spectator = createHttp());

it('...', () => {
  spectator.service.foo();
});

Deprecated createService in favour of createServiceFactory

Instead of creating a service with createService, we recommend you to use the new createServiceFactory which supports more options, like mocks, entry components, etc.

⚠️ Before:

const service = createService(SomeService);

it('...', () => {
  service.foo();
});

✅ After:

const createService = createServiceFactory(SomeService);
let spectator: SpectatorService<SomeService>;

beforeEach(() => spectator = createService());

it('...', () => {
  spectator.service.foo();
});

RECOMMENDATIONS

Use createDirectiveFactory for directives 😎

Spectator 4 has a special factory for directives. The previously recommended way was to use createHostComponentFactory for that. While this is still perfectly supported (using createHostFactory), we recommend to use the new createDirectiveFactory instead to benefit from better semantics and a better query strategy.