Forem: Felipe Armoni

Typescript Library Template

Felipe Armoni — Tue, 04 Jul 2023 19:33:07 +0000

TLDR

I've created a Typescript library template that has some pre-configured boilerplate, you can find it here: https://github.com/komyg/library-template.

The Template

This template uses:

Rollup for bundling.
ESLint and Prettier for linting and formatting.
Jest for testing.

It is structured as a monorepo, with a lib package for the library and a runner package that is meant to call the library and thus enable manual testing during the development.

Please note that you must build the library (npm run build -w lib), before using it on the runner.

The library itself does not have any dependencies, and it can be imported in a browser or in a node application.

Should I allow my teammates to make mistakes, so that they can learn from them?

Felipe Armoni — Thu, 09 Sep 2021 14:55:40 +0000

Hi, I am working to become a tech lead at my company and my manager posed me this question:

If I become a tech lead, should I allow my teammates to make minor mistakes so that they can learn from them?

His reasoning was that people will learn much more from a mistake than from direct guidance, and that we could take on the cost of a small mistake, so that the team can grow.

What are your thoughts on this?

Angular Fire and Forget Polling with NgRx, RxJS and Unit Tests

Felipe Armoni — Tue, 23 Jun 2020 00:51:43 +0000

In this tutorial I would like to show you how you can poll a service using Observables (RxJS) and the NgRx Store and Effects. It assumes that you have a basic knowledge of Angular, Typescript, NgRx and RxJS.

The full code for this tutorial is available in this repository.

You can see the finished version of this tutorial here.

Our Goal

The goal of this tutorial is to setup a fire and forget polling. By fire and forget I mean to say that I would like to call the starting action of the polling only once and have the polling go on forever.

That being said, it would be easier to setup a polling strategy where I would call a given action from a component every X seconds, but then, if the user navigates away from this component, the polling would stop and this would violate our goal above.

Our implementation strategy will be the following:

Create a mock service that will be polled every 3 seconds.
Create actions and reducers to start the polling and handle its results.
Create an Effect that will do the actual polling of our service and will dispatch the success and fail actions.
Create a component that will listen to the polling's results.

Initial setup

For the initial setup add the following packages:

NgRx Store: ng add @ngrx/store
NgRx Effects: ng add @ngrx/effects
NgRx DevTools: ng add @ngrx/store-devtools
Angular Material: ng add @angular/material
Jasmine Marbles: yarn add -D jasmine-marbles

Environment

Before web begin we should also add an environment variable. Edit the src/environments/environment.ts and src/environments/environment.prod.ts files to add a polling interval of 3 seconds (or 3.000 milliseconds):

export const environment = {
  production: true,
  pollingInterval: 3000,
};

Random number service

For this tutorial we will create a simple service that will return a random number when called. In order to simulate a more accurate behavior, we are going to return this random number inside an Observable, because this is what would happen if we were to poll a remote server for example.

To start create a new folder called: src/app/services/random-number. Then create a new service template with the command: ng g service services/random-number/random-number.

Copy and paste the following code into the random-number.service.ts file:

import { Injectable } from '@angular/core';
import { of, Observable } from 'rxjs';

@Injectable({
  providedIn: 'root',
})
export class RandomNumberService {
  constructor() {}

  getRandomInteger(min: number, max: number): Observable<number> {
    const num = Math.floor(Math.random() * (max - min)) + min;
    return of(num);
  }
}

What this service does is just generate a random integer between max and min and return it as an Observable. As stated before, the purpose of the Observable here is to simulate the behavior of an API call.

Unit testing our service

To make sure our service works as expected, we can add a unit test in the file: src/app/services/random-number/random-number.service.spec.ts:

import { TestBed } from '@angular/core/testing';

import { RandomNumberService } from './random-number.service';

describe('RandomNumberService', () => {
  let service: RandomNumberService;

  beforeEach(() => {
    TestBed.configureTestingModule({});
    service = TestBed.inject(RandomNumberService);
  });

  it('should be created', () => {
    expect(service).toBeTruthy();
  });

  it('should generate a random number', (done: DoneFn) => {
    service.getRandomInteger(0, 99).subscribe((result) => {
      expect(result).toBeGreaterThanOrEqual(0);
      expect(result).toBeLessThan(100);
      done();
    });
  });
});

Actions

For the actions, create a new file: src/app/actions/random-number.actions.ts and paste the contents below:

import { createAction, props } from '@ngrx/store';

export const START_POLLING = '[Polling] start';
export const POLLING_SUCCESS = '[Polling] success';
export const POLLING_ERROR = '[Polling] error';

export const startPolling = createAction(
  START_POLLING,
  props<{ min: number; max: number }>()
);

export const pollingSuccess = createAction(
  POLLING_SUCCESS,
  props<{ randomNumber: number }>()
);

export const pollingError = createAction(
  POLLING_ERROR,
  props<{ error: any }>()
);

Reducers

Now let's create the random number reducer. To do this, create the file: src/app/reducers/random-number/random-number.reducer.ts and paste the code below:

import * as actions from '../../actions/random-number.actions';
import { on, createReducer } from '@ngrx/store';
import { environment } from 'src/environments/environment';

export interface RandomNumberState {
  min: number;
  max: number;
  randomNumber: number;
  errorMsg: string;
  pollingInterval: number;
}

const initialState: RandomNumberState = {
  min: 0,
  max: 99,
  randomNumber: 0,
  errorMsg: '',
  pollingInterval: environment.pollingInterval,
};

export const randomNumberReducer = createReducer(
  initialState,
  on(actions.startPolling, (state, { min, max }) => ({ ...state, min, max })),
  on(actions.pollingSuccess, (state, { randomNumber }) => ({
    ...state,
    randomNumber,
    errorMsg: '',
  })),
  on(actions.pollingError, (state, { error }) => ({
    ...state,
    errorMsg: error.message,
  }))
);

This is a simple reducer that updates the current state with the min and max values for the random number generator and also stores either the resulting random number or an error message.

Registering the random number reducer

To register our random number reducer, create the file: src/app/state/state.ts and paste the contents below:

import { ActionReducerMap } from '@ngrx/store';
import {
  RandomNumberState,
  randomNumberReducer,
} from '../reducers/random-number/random-number.reducer';

export interface State {
  randomNumberFeature: RandomNumberState;
}

export const reducers: ActionReducerMap<State> = {
  randomNumberFeature: randomNumberReducer,
};

export const selectRandomNumberFeature = (appState: State) =>
  appState.randomNumberFeature;

As you can see we created a new state feature called randomNumberFeature and associated our reducer to it. We also created a feature selector that we will use below.

Then open the src/app/app.module.ts file and add our reducers to the store config:

/* [...] */
import { reducers } from './state/state';

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    StoreModule.forRoot(reducers),
    /* [...] */

export class AppModule {}

Creating selectors

To make it easier for us to work with our state, let's create a few selectors. Create the file: src/app/state/random-number/random-number.selector.ts and paste the contents below:

import { createSelector } from '@ngrx/store';
import { selectRandomNumberFeature } from '../state';
import { RandomNumberState } from 'src/app/reducers/random-number/random-number.reducer';

export const selectMinMax = createSelector(
  selectRandomNumberFeature,
  (state: RandomNumberState) => ({ min: state.min, max: state.max })
);

export const selectRandomNumber = createSelector(
  selectRandomNumberFeature,
  (state: RandomNumberState) => state.randomNumber
);

export const selectPollingInterval = createSelector(
  selectRandomNumberFeature,
  (state: RandomNumberState) => state.pollingInterval
);

Unit testing or reducer

Now let's add a unit test to validate if our reducer is working correctly. Create the file: src/app/reducers/random-number/random-number.reducer.spec.ts and paste the contents below:

import {
  startPolling,
  pollingSuccess,
  pollingError,
} from 'src/app/actions/random-number.actions';
import {
  randomNumberReducer,
  RandomNumberState,
} from './random-number.reducer';

describe('Random Number Reducer', () => {
  let initialState: RandomNumberState;
  beforeEach(() => {
    initialState = {
      min: 0,
      max: 100,
      randomNumber: 0,
      errorMsg: '',
      pollingInterval: 10,
    };
  });

  it('should handle the start polling action', () => {
    const action = startPolling({ min: 1, max: 5 });
    const result = randomNumberReducer(initialState, action);
    expect(result.min).toBe(1);
    expect(result.max).toBe(5);
  });

  it('should handle the polling success action', () => {
    const action = pollingSuccess({ randomNumber: 42 });
    const result = randomNumberReducer(initialState, action);
    expect(result.randomNumber).toBe(42);
  });

  it('should handle the polling error action', () => {
    const action = pollingError({ error: new Error('Fake error') });
    const result = randomNumberReducer(initialState, action);
    expect(result.errorMsg).toBe('Fake error');
  });
});

Effects

Now that we have finished setting up our reducer we can setup a side effect that will implement our polling. To do this create the file:
src/app/effects/random-number/random-number.effect.ts and paste the contents below:

import { Injectable } from '@angular/core';
import { Actions, createEffect, ofType } from '@ngrx/effects';
import { select, Store } from '@ngrx/store';
import { asyncScheduler, EMPTY, of, timer } from 'rxjs';
import {
  catchError,
  map,
  switchMap,
  takeUntil,
  withLatestFrom,
} from 'rxjs/operators';
import {
  pollingError,
  pollingSuccess,
  startPolling,
} from 'src/app/actions/random-number.actions';
import { RandomNumberService } from 'src/app/services/random-number/random-number.service';
import { selectPollingInterval } from 'src/app/state/random-number/random-number.selector';
import { State } from 'src/app/state/state';

@Injectable()
export class RandomNumberEffects {
  randomNumberPolling$ = createEffect(
    () => ({ scheduler = asyncScheduler, stopTimer = EMPTY } = {}) =>
      this.actions$.pipe(
        // Filter action type
        ofType(startPolling),
        // Get the polling interval
        withLatestFrom(this.store$.pipe(select(selectPollingInterval))),
        switchMap(([action, pollingInterval]) =>
          // Start polling
          timer(0, pollingInterval, scheduler).pipe(
            // Stop the polling (used only in testing)
            takeUntil(stopTimer),
            switchMap(() =>
              this.randomNumberService
                .getRandomInteger(action.min, action.max)
                .pipe(
                  map((randomNumber) => pollingSuccess({ randomNumber })),
                  catchError((error) => {
                    console.error(error);
                    return of(pollingError({ error }));
                  })
                )
            )
          )
        )
      )
  );

  constructor(
    private actions$: Actions,
    private store$: Store<State>,
    private randomNumberService: RandomNumberService
  ) {}
}

There are a lot of things happening on our effect to create the polling. So we will break it down from the top:

() => ({ scheduler = asyncScheduler, stopTimer = EMPTY } = {}) =>: we start our effect by passing two variables to it: scheduler and stopTimer, both of which have the default values of asyncScheduler and EMTPY respectively. They are here, because we want to be able to replace the default asyncScheduler provided by RxJS in our tests.
ofType(startPolling),: we use this filter to run our effect when the action startPolling is called.
withLatestFrom(this.store$.pipe(select(selectPollingInterval))),: here we take the polling interval from our store state and pass it forward to our test (we could use the value directly from the environment variables, but I wanted to illustrate this use case).
switchMap(([action, pollingInterval]) =>: we use the switchMap here, because it will subscribe only to the latest observable returned by the timer, this means that if our service does not return a response within the polling interval, we cancel this request and make a new one. A more through explanation of what a switchMap does is available in the RxJS documentation.
timer(0, pollingInterval, scheduler): this the part of our effect that does the polling. It will make a request to our service immediately and then do it again after the time prescribed in the pollingInterval has passed. Notice that we are passing the scheduler variable to it. This is done to make our effect testable with marbles.
takeUntil(stopTimer),: this statement will stop our polling when the stopTimer observable emits. We are only using this for testing purposes.
switchMap(() =>: we use this switch map to encapsulate a call to our service.
this.randomNumberService.getRandomInteger(action.min, action.max): this is the actual call for our random number service. It returns an Observable containing a random number.
map((randomNumber) => pollingSuccess({ randomNumber })),: if the call to our random number service succeeds, we map the result to the pollingSuccess action.
catchError((error) =>: if the call to our random number service fails, we return the pollingError action.

Registering our effect

To register our effect, open the src/app.module.ts file and add it to the effects declaration: EffectsModule.forRoot([RandomNumberEffects]),.

Testing our effect

Now that we have our effect created, let's add a unit test for it. Create the file: src/app/effects/random-number/random-number.effect.spec.ts and paste the contents below:

import { TestBed } from '@angular/core/testing';
import { provideMockActions } from '@ngrx/effects/testing';
import { selectPollingInterval } from 'src/app/state/random-number/random-number.selector';
import { RandomNumberService } from 'src/app/services/random-number/random-number.service';
import { Action } from '@ngrx/store';
import { Observable } from 'rxjs';
import { provideMockStore } from '@ngrx/store/testing';
import { cold, getTestScheduler, hot } from 'jasmine-marbles';
import { RandomNumberEffects } from './random-number.effect';
import {
  startPolling,
  pollingSuccess,
  pollingError,
} from 'src/app/actions/random-number.actions';
import { TestScheduler } from 'rxjs/testing';

describe('Random Number Effect', () => {
  let actions$: Observable<Action>;
  let effects: RandomNumberEffects;
  let service: jasmine.SpyObj<RandomNumberService>;
  let testScheduler: TestScheduler;

  beforeEach(() => {
    TestBed.configureTestingModule({
      providers: [
        RandomNumberEffects,
        // Mock Random number service
        {
          provide: RandomNumberService,
          useValue: jasmine.createSpyObj('service-spy', ['getRandomInteger']),
        },
        provideMockActions(() => actions$),
        provideMockStore({
          selectors: [{ selector: selectPollingInterval, value: 30 }],
        }),
      ],
    });

    effects = TestBed.inject(RandomNumberEffects);
    service = TestBed.inject(RandomNumberService) as jasmine.SpyObj<
      RandomNumberService
    >;

    // Get the test scheduler so that we can simulate the async behavior
    testScheduler = getTestScheduler();
  });

  it('should successfully poll for random numbers', () => {
    // Mock service response
    service.getRandomInteger.and.returnValues(
      cold('a|', { a: 42 }),
      cold('b|', { b: 33 }),
      cold('c|', { c: 2 })
    );

    // Call the action observable with the Action that will be processed by the effect.
    actions$ = hot('a', { a: startPolling({ min: 0, max: 99 }) });

    // Create the expected result
    const expected = hot('a--b--c', {
      a: pollingSuccess({ randomNumber: 42 }),
      b: pollingSuccess({ randomNumber: 33 }),
      c: pollingSuccess({ randomNumber: 2 }),
    });

    // Make sure we stop the timer at the end of the test
    const stopTimer = hot('-------a', { a: 'stop' });

    expect(
      effects.randomNumberPolling$({ scheduler: testScheduler, stopTimer })
    ).toBeObservable(expected);
  });

  it('should handle a timeout', () => {
    service.getRandomInteger.and.returnValues(
      cold('----a|', { a: 42 }),
      cold('b|', { b: 33 }),
      cold('-c|', { c: 2 })
    );

    actions$ = hot('a', { a: startPolling({ min: 0, max: 99 }) });
    const expected = hot('---b---c', {
      b: pollingSuccess({ randomNumber: 33 }),
      c: pollingSuccess({ randomNumber: 2 }),
    });

    const stopTimer = hot('-------a', { a: 'stop' });

    expect(
      effects.randomNumberPolling$({ scheduler: testScheduler, stopTimer })
    ).toBeObservable(expected);
  });

  it('should handle an error', () => {
    service.getRandomInteger.and.returnValues(
      cold('-#'),
      cold('b|', { b: 33 }),
      cold('c|', { c: 2 })
    );

    actions$ = hot('a', { a: startPolling({ min: 0, max: 99 }) });
    const expected = hot('-a-b--c', {
      a: pollingError({ error: 'error' }),
      b: pollingSuccess({ randomNumber: 33 }),
      c: pollingSuccess({ randomNumber: 2 }),
    });

    const stopTimer = hot('-------a', { a: 'stop' });

    expect(
      effects.randomNumberPolling$({ scheduler: testScheduler, stopTimer })
    ).toBeObservable(expected);
  });
});

In the test above we are making extensive use of marble tests. I took the summary below from this article. If you've never worked with marble tests, I strongly suggest you read it in its entirety.

To write a test with marble diagrams you will need to stick to a convention of characters that will help visualize the observable stream:

During the tests, the sens of time (when values are emitted) is handle by the RxJS TestScheduler
(dash): simulate the passage of time, one dash correspond to a frame which can be perceived as 10ms in our tests, —--- is 40 ms
a-z (a to z): represent an emission, -a--b---c stands for “emit a at 20ms, b at 50ms, c at 90ms”
| (pipe): emit a completed (end of the stream), ---a-| stands for emit ‘a’ at 40ms then complete (60ms)
# (pound sign): indicate an error (end of the stream), —--a--# emit a at 40ms then an error at 70ms
( ) (parenthesis): multiple values together in the same unit of time, —--(ab|) stands for emit a b at 40ms then complete (40ms)
^ (caret): indicate a subscription point, —^-- subscription starting at ^
! (exclamation point): indicate the end of a subscription point, —^--! subscription starting at ^ and ending at !

These strings are a powerful syntax that will permit you to simulate the passage of time, emit a value, a completion, an error etc.. all that, without creating the observable yourself.

You also have some methods to parse and create observables from your diagrams:
cold()

cold(marbles: string, values?: object, error?: any) Subscription starts when test begins:

cold(--a--b--|, { a: 'Hello', b: 'World' }) → Emit ‘Hello’ at 30ms and ‘World’ at 60ms, complete at 90ms.
hot()

hot(marbles: string, values?: object, error?: any) Behaves like subscription starts at point of caret:

hot(--^--a--b--|, { a: 'Hello', b: 'World' }) → Subscription begins at point of caret, then emit ‘Hello’ at 30ms and ‘World’ at 60ms, complete at 90ms.

Here is the breakdown of the main parts of the first test:

testScheduler = getTestScheduler();: We have to get the test scheduler from the jasmine marbles in order the test the async behaviors such as the timer and the timeout.
service.getRandomInteger.and.returnValues(cold('a|', { a: 42 }), cold('b|', { b: 33 }), cold('c|', { c: 2 }));: mock our service so that it returns test observables each time it is called.
const expected = hot('a--b--c', { a: pollingSuccess({ randomNumber: 42 }), b: pollingSuccess({ randomNumber: 33 }), c: pollingSuccess(randomNumber: 2 }), });: here we setup our test's expected result. Notice the polling effect on the marble diagram and that we don't need to keep calling the action$ observable to make the polling work.
const stopTimer = hot('-------a', { a: 'stop' });: here we create an observable that emits at the end of the test. If we don't do this, the polling will continue to run after we are done, and this will generate an error on the expect assertion.
expect(effects.randomNumberPolling$({ scheduler: testScheduler, stopTimer })).toBeObservable(expected);: here are testing our effect. Notice that we pass both the testScheduler and the stopTimer as arguments. This way we can override the default async scheduler from RxJS and stop the timer once our test is done.

The second test very similar to the first one, but in this case we are forcing a timeout using an observable that will emit a result after the specified polling interval of 30: cold('----a|', { a: 42 }),. Our effect will handle the timeout error and try again.

The last test is also similar to the other ones, but in this case we are simulating an error using this observable: cold('-#'),. Our effect should handle this error and try again.

Components

Now that we have our effect up and running, let's create some components.

Note: the fastest way to generate a new component is by using the Angular CLI Schematics and the command: ng generate component [component name].

Random number

This component will subscribe to the selectRandomNumber selector using the async pipe and display our random number as it is updated by our service.

Schematics command: ng g components/random-number

src/app/components/random-number/random-number.component.html:

<div class="root">
  <h3 id="random-number">Your random number is: {{ randomNumber$ | async }}</h3>
</div>

src/app/components/random-number/random-number.component.scss: this file is empty.

src/app/components/random-number/random-number.component.ts:

import { Component, OnInit } from '@angular/core';
import { Store, select } from '@ngrx/store';
import { Observable } from 'rxjs';
import { selectRandomNumber } from 'src/app/state/random-number/random-number.selector';

@Component({
  selector: 'app-random-number',
  templateUrl: './random-number.component.html',
  styleUrls: ['./random-number.component.scss'],
})
export class RandomNumberComponent implements OnInit {
  randomNumber$: Observable<number>;

  constructor(private store$: Store) {}

  ngOnInit(): void {
    this.randomNumber$ = this.store$.pipe(select(selectRandomNumber));
  }
}

src/app/components/random-number/random-number.component.spec.ts:

import { async, ComponentFixture, TestBed } from '@angular/core/testing';

import { RandomNumberComponent } from './random-number.component';
import { provideMockStore } from '@ngrx/store/testing';
import { selectRandomNumber } from 'src/app/state/random-number/random-number.selector';
import { By } from '@angular/platform-browser';

describe('RandomNumberComponent', () => {
  let component: RandomNumberComponent;
  let fixture: ComponentFixture<RandomNumberComponent>;

  beforeEach(async(() => {
    TestBed.configureTestingModule({
      providers: [
        provideMockStore({
          selectors: [{ selector: selectRandomNumber, value: 42 }],
        }),
      ],
      declarations: [RandomNumberComponent],
    }).compileComponents();
  }));

  beforeEach(() => {
    fixture = TestBed.createComponent(RandomNumberComponent);
    component = fixture.componentInstance;
    fixture.detectChanges();
  });

  it('should create', () => {
    expect(component).toBeTruthy();
  });

  it('should display the current random number', () => {
    const randomNumber = fixture.debugElement.query(By.css('#random-number'));
    expect(randomNumber.nativeElement.textContent).toContain(42);
  });
});

The Min Max Input Component

This component allows our users to choose the min and max value of our random numbers and allows them to start the polling process. Notice that you can always restart the polling with new values.

This component uses the Angular Reactive Forms, so you have to add an import to the ReactiveFormsModule in the src/app.module.ts file. You should also add imports to the Angular Material components that we are using:

/* [...] */
imports: [
    BrowserModule,
    ReactiveFormsModule,
    MatFormFieldModule,
    MatButtonModule,
    MatInputModule,
/* [...] */

Schematics command: ng g component components/min-max-input

src/app/components/min-max-input/min-max-input.component.html:

<form class="root" [formGroup]="inputForm" (ngSubmit)="onSubmit()">
  <mat-form-field>
    <mat-label>Minimum Value</mat-label>
    <input matInput formControlName="minInput" />
  </mat-form-field>
  <mat-form-field>
    <mat-label>Maximum Value</mat-label>
    <input matInput formControlName="maxInput" />
  </mat-form-field>
  <button id="submit-btn" type="submit" mat-flat-button color="primary">
    Start polling!
  </button>
</form>

src/app/components/min-max-input/min-max-input.component.scss:

.root {
  display: flex;
  flex-direction: column;
  align-content: center;
}

src/app/components/min-max-input/min-max-input.component.ts:

import { Component, OnInit } from '@angular/core';
import { FormGroup, FormControl, Validators } from '@angular/forms';
import { Store } from '@ngrx/store';
import { startPolling } from 'src/app/actions/random-number.actions';

@Component({
  selector: 'app-min-max-input',
  templateUrl: './min-max-input.component.html',
  styleUrls: ['./min-max-input.component.scss'],
})
export class MinMaxInputComponent implements OnInit {
  inputForm: FormGroup;

  constructor(private store$: Store) {}

  ngOnInit(): void {
    this.inputForm = new FormGroup({
      minInput: new FormControl(0, [
        Validators.required,
        Validators.pattern('^[0-9]*$'),
      ]),
      maxInput: new FormControl(99, [
        Validators.required,
        Validators.pattern('^[0-9]*$'),
      ]),
    });
  }

  onSubmit() {
    if (this.inputForm.invalid) {
      console.warn('The form is invalid');
      return;
    }

    this.store$.dispatch(
      startPolling({
        min: this.inputForm.get('minInput').value,
        max: this.inputForm.get('maxInput').value,
      })
    );
  }
}

src/app/components/min-max-input/min-max-input.component.spec.ts:

import { async, ComponentFixture, TestBed } from '@angular/core/testing';
import { MinMaxInputComponent } from './min-max-input.component';
import { ReactiveFormsModule } from '@angular/forms';
import { TestbedHarnessEnvironment } from '@angular/cdk/testing/testbed';
import { HarnessLoader } from '@angular/cdk/testing';
import { MatButtonHarness } from '@angular/material/button/testing';
import { provideMockStore, MockStore } from '@ngrx/store/testing';
import { startPolling } from 'src/app/actions/random-number.actions';
import { MatButtonModule } from '@angular/material/button';

describe('MinMaxInputComponent', () => {
  let component: MinMaxInputComponent;
  let fixture: ComponentFixture<MinMaxInputComponent>;
  let loader: HarnessLoader;

  beforeEach(async(() => {
    TestBed.configureTestingModule({
      imports: [ReactiveFormsModule, MatButtonModule],
      declarations: [MinMaxInputComponent],
      providers: [provideMockStore()],
    }).compileComponents();
  }));

  beforeEach(() => {
    fixture = TestBed.createComponent(MinMaxInputComponent);
    loader = TestbedHarnessEnvironment.loader(fixture);
    component = fixture.componentInstance;
    fixture.detectChanges();
  });

  it('should create', () => {
    expect(component).toBeTruthy();
  });

  it('should call an action when the form is submitted', async () => {
    const mockStore = TestBed.inject(MockStore);
    spyOn(mockStore, 'dispatch');

    const submitBtn = await loader.getHarness(MatButtonHarness);

    component.inputForm.get('minInput').setValue(10);
    component.inputForm.get('maxInput').setValue(100);

    await submitBtn.click();

    expect(mockStore.dispatch).toHaveBeenCalledWith(
      startPolling({ min: 10, max: 100 })
    );
  });
});

App component

This is the entry point app component. To make things more organized, I moved it from the src/app folder to the src/app/components/app folder.

src/app/components/app/app.component.html:

<div class="root">
  <div class="app-content">
    <h1 class="app-header">Angular Fire and Forget Polling</h1>
    <app-random-number></app-random-number>
    <app-min-max-input></app-min-max-input>
  </div>
</div>

src/app/components/app/app.component.scss:

.root {
  display: flex;
  flex-direction: column;
  align-items: center;

  padding: 0 3rem;

  @media (min-width: 1200px) {
    margin: 0 20rem;
  }

  @media (min-width: 992px) {
    margin: 0 10rem;
  }

  .app-content {
    width: 100%;
  }

  .app-header {
    margin: 1rem 0;
    text-align: center;
  }
}

src/app/components/app/app.component.ts:

import { Component, OnInit } from '@angular/core';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss'],
})
export class AppComponent implements OnInit {
  constructor() {}

  ngOnInit(): void {}
}

src/app/components/app/app.component.spec.ts:

import { async, ComponentFixture, TestBed } from '@angular/core/testing';
import { AppComponent } from './app.component';
import { NO_ERRORS_SCHEMA } from '@angular/core';

describe('AppComponent', () => {
  let component: AppComponent;
  let fixture: ComponentFixture<AppComponent>;

  beforeEach(async(() => {
    TestBed.configureTestingModule({
      declarations: [AppComponent],
      schemas: [NO_ERRORS_SCHEMA],
    }).compileComponents();
  }));

  beforeEach(() => {
    fixture = TestBed.createComponent(AppComponent);
    component = fixture.componentInstance;
    fixture.detectChanges();
  });

  it('should create', () => {
    expect(component).toBeTruthy();
  });
});

Registering the components

Don't forget to register all the components in the app.module: declarations: [AppComponent, RandomNumberComponent, MinMaxInputComponent],

Conclusion

Now that everything is created you can either run the unit tests using the command: ng test or run the app itself using the command: ng serve.

Unit Tests with Enzyme and Apollo Graphql

Felipe Armoni — Tue, 25 Feb 2020 18:26:46 +0000

This is a three part tutorial series in which we will build a simple shopping cart app using React and Apollo Graphql. The idea is to build a table in which the user can choose which Rick and Morty action figures he wants to buy.

In this third part we will add unit tests to our components and our resolvers.

Note: usually I think that it is a good practice to write the tests at the same time as you are writing the code (see TDD - Test Driven Development), but I chose not do to this on this tutorial series, because I thought it would be clearer to separate the subjects.

This tutorial builds on top of the code generated in the Part 2. You can get it here.

The complete code for the Part 3 is available in this repository and the website here: https://komyg.github.io/rm-shop-v3/.

Note: this tutorial assumes that you have a working knowledge of React and Typescript.

Getting Started

To begin, clone the repository that we used on the Part 2.

After you cloned the repository, run yarn install to download the necessary packages.

Configuring Enzyme

In this tutorial we are going to use Enzyme and Jest to run unit tests on our code. The Enzyme configuration below was taken from the Create React App official documentation.

First let's add the necessary packages: yarn add -D enzyme @types/enzyme enzyme-adapter-react-16 react-test-renderer jest-enzyme wait-for-expect.

Then let's setup our tests by creating the file: src/setupTests.js and pasting the contents below:

import {
  configure
} from 'enzyme';
import Adapter from 'enzyme-adapter-react-16';
import 'jest-enzyme';

configure({
  adapter: new Adapter()
});

Also delete the src/setupTests.ts file if you have it.

Running the tests

At any point in this tutorial you can execute the command yarn test to run the tests we've written so far. You can also add the file name to the end of this command to run a single test suite.

Testing the resolvers

To test our resolvers, we are going to setup a mock Apollo Client and check the inputs and outputs from them. A good way to see what comes in and out of a resolver is to use console.log statements.

Set unit price

The first resolver we are going to test is the setUnitPrice. Let's start by creating a test file: resolvers/set-unit-price.resolver.test.ts and then pasting the contents below on it:

import setUnitPrice from './set-unit-price.resolver';

describe('Set Unit Price Resolver', () => {
  it('should set the unit price for a regular character', () => {
    const mockCharacter: any = {
      id: '3',
      __typename: 'Character',
      name: 'Summer Smith',
    };

    const result = setUnitPrice(mockCharacter, null, null as any, null);
    expect(result).toBe(5);
  });

  it('should set the unit price for a special character', () => {
    const mockCharacter: any = {
      id: '1',
      __typename: 'Character',
      name: 'Rick Sanchez',
    };

    const result = setUnitPrice(mockCharacter, null, null as any, null);
    expect(result).toBe(10);
  });
});

The purpose of this resolver is to assign the price of 10 USD to Rick and Morty and 5 USD to everyone else. The way that Apollo does this, is by sending every new Character that comes from the backend through this resolver in the root param in order to get the unitPrice value. This is what we are reproducing in our test.

In this case we don't need to setup a mock client for the test to work, however we are telling the compiler that the mockCharacter and the context are of the any type, so that it won't complain that the mockCharacter is missing some properties and that we can't assign null to the context.

Increase chosen quantity

Next we will test the increaseChosenQuantity. To do this, create the file resolvers/increase-chosen-quantity.resolver.test.ts and paste the contents below:

import { InMemoryCache, IntrospectionFragmentMatcher } from 'apollo-cache-inmemory';
import ApolloClient from 'apollo-client';
import fragmentData from '../generated/fragment-matcher.json';
import increaseChosenQuantity from './increase-chosen-quantity.resolver';
import {
  IncreaseChosenQuantityMutation,
  IncreaseChosenQuantityDocument,
  CharacterDataFragment,
  CharacterDataFragmentDoc,
  GetShoppingCartQuery,
  GetShoppingCartDocument,
} from '../generated/graphql';

describe('Add To Cart Resolver', () => {
  let cache: InMemoryCache;
  let client: ApolloClient<any>;

  beforeEach(() => {
    // Create mock fragment matcher
    const fragmentMatcher = new IntrospectionFragmentMatcher({
      introspectionQueryResultData: fragmentData,
    });

    // Create mock client and cache
    cache = new InMemoryCache({ addTypename: false, fragmentMatcher, freezeResults: true });
    client = new ApolloClient({
      cache,
      resolvers: { Mutation: { increaseChosenQuantity } }, // Resolver we want to test
      assumeImmutableResults: true,
    });

    // Initialize the cache with the desired state
    cache.writeData({ data: mockData });
  });

  it('should increase a character chosen quantity', async () => {
    const result = await client.mutate<IncreaseChosenQuantityMutation>({
      mutation: IncreaseChosenQuantityDocument,
      variables: { input: { id: '1' } },
    });
    expect(result.data?.increaseChosenQuantity).toBe(true);

    const character = client.readFragment<CharacterDataFragment>({
      fragment: CharacterDataFragmentDoc,
      id: 'Character:1',
    });
    expect(character?.chosenQuantity).toBe(1);
  });

  it('should update the shopping cart', async () => {
    const result = await client.mutate<IncreaseChosenQuantityMutation>({
      mutation: IncreaseChosenQuantityDocument,
      variables: { input: { id: '1' } },
    });
    expect(result.data?.increaseChosenQuantity).toBe(true);

    const shoppingCartQuery = client.readQuery<GetShoppingCartQuery>({
      query: GetShoppingCartDocument,
    });
    expect(shoppingCartQuery?.shoppingCart.numActionFigures).toBe(1);
    expect(shoppingCartQuery?.shoppingCart.totalPrice).toBe(10);
  });
});

const mockData = {
  characters: {
    results: [
      {
        id: '1',
        __typename: 'Character',
        name: 'Rick Sanchez',
        species: 'Human',
        image: 'https://rickandmortyapi.com/api/character/avatar/1.jpeg',
        chosenQuantity: 0,
        unitPrice: 10,
        origin: {
          id: '1',
          __typename: 'Location',
          name: 'Earth (C-137)',
        },
        location: {
          id: '20',
          __typename: 'Location',
          name: 'Earth (Replacement Dimension)',
        },
      },
    ],
  },
  shoppingCart: {
    __typename: 'ShoppingCart',
    id: btoa('ShoppingCart:1'),
    totalPrice: 0,
    numActionFigures: 0,
  },
};

There is a lot going on in this file, so we are going to break it down:

First we begin by setting up a mock Apollo Client complete with a fragmentMatcher, an InMemoryCache and the resolver that we want to test. Note that both the client and the cache should have the same configurations as the real client, but with the addTypename property as false.

Then we initialize the InMemoryCache with a mock state by passing the mockData variable to the cache.writeData function. It is important to mention that all fields that are part of any query, fragment or mutation that is ran on this test, must be present on the mock data, otherwise the Apollo will throw an error. For example, if we omit the character's name parameter in the mockData, then the Apollo will throw an error, because the characterData fragment that is used inside the increaseChosenQuantity resolver contains this field.

Once the cache is initialized, we run two tests to see if the Character and the ShoppingCart are being successfully updated when the mutation is ran.

Decrease chosen quantity

Next, let's create a test for the decreaseChosenQuantity resolver. Start by creating the file: resolvers/decrease-chosen-quantity.resolver.test.ts and pasting the contents below:

import { InMemoryCache, IntrospectionFragmentMatcher } from 'apollo-cache-inmemory';
import ApolloClient from 'apollo-client';
import fragmentData from '../generated/fragment-matcher.json';
import {
  CharacterDataFragment,
  CharacterDataFragmentDoc,
  DecreaseChosenQuantityDocument,
  DecreaseChosenQuantityMutation,
  GetShoppingCartDocument,
  GetShoppingCartQuery,
} from '../generated/graphql';
import decreaseChosenQuantity from './decrease-chosen-quantity.resolver';

describe('Add To Cart Resolver', () => {
  let cache: InMemoryCache;
  let client: ApolloClient<any>;

  beforeEach(() => {
    // Create mock fragment matcher
    const fragmentMatcher = new IntrospectionFragmentMatcher({
      introspectionQueryResultData: fragmentData,
    });

    // Create mock client and cache
    cache = new InMemoryCache({ addTypename: false, fragmentMatcher, freezeResults: true });
    client = new ApolloClient({
      cache,
      resolvers: { Mutation: { decreaseChosenQuantity } }, // Resolver we want to test
      assumeImmutableResults: true,
    });

    // Initialize the cache with the desired state
    cache.writeData({ data: mockData });
  });

  it('should decrease a character chosen quantity', async () => {
    const result = await client.mutate<DecreaseChosenQuantityMutation>({
      mutation: DecreaseChosenQuantityDocument,
      variables: { input: { id: '1' } },
    });
    expect(result.data?.decreaseChosenQuantity).toBe(true);

    const character = client.readFragment<CharacterDataFragment>({
      fragment: CharacterDataFragmentDoc,
      id: 'Character:1',
    });
    expect(character?.chosenQuantity).toBe(0);
  });

  it('should update the shopping cart', async () => {
    const result = await client.mutate<DecreaseChosenQuantityMutation>({
      mutation: DecreaseChosenQuantityDocument,
      variables: { input: { id: '1' } },
    });
    expect(result.data?.decreaseChosenQuantity).toBe(true);

    const shoppingCartQuery = client.readQuery<GetShoppingCartQuery>({
      query: GetShoppingCartDocument,
    });
    expect(shoppingCartQuery?.shoppingCart.numActionFigures).toBe(0);
    expect(shoppingCartQuery?.shoppingCart.totalPrice).toBe(0);
  });

  it('should not decrease the chosen quantity below 0', async () => {
    await client.mutate<DecreaseChosenQuantityMutation>({
      mutation: DecreaseChosenQuantityDocument,
      variables: { input: { id: '1' } },
    });
    await client.mutate<DecreaseChosenQuantityMutation>({
      mutation: DecreaseChosenQuantityDocument,
      variables: { input: { id: '1' } },
    });

    const character = client.readFragment<CharacterDataFragment>({
      fragment: CharacterDataFragmentDoc,
      id: 'Character:1',
    });
    expect(character?.chosenQuantity).toBe(0);
  });

  it('should not decrease the shopping cart price and quantity below 0', async () => {
    await client.mutate<DecreaseChosenQuantityMutation>({
      mutation: DecreaseChosenQuantityDocument,
      variables: { input: { id: '1' } },
    });
    await client.mutate<DecreaseChosenQuantityMutation>({
      mutation: DecreaseChosenQuantityDocument,
      variables: { input: { id: '1' } },
    });

    const shoppingCartQuery = client.readQuery<GetShoppingCartQuery>({
      query: GetShoppingCartDocument,
    });
    expect(shoppingCartQuery?.shoppingCart.numActionFigures).toBe(0);
    expect(shoppingCartQuery?.shoppingCart.totalPrice).toBe(0);
  });
});

const mockData = {
  characters: {
    results: [
      {
        id: '1',
        __typename: 'Character',
        name: 'Rick Sanchez',
        species: 'Human',
        image: 'https://rickandmortyapi.com/api/character/avatar/1.jpeg',
        chosenQuantity: 1,
        unitPrice: 10,
        origin: {
          id: '1',
          __typename: 'Location',
          name: 'Earth (C-137)',
        },
        location: {
          id: '20',
          __typename: 'Location',
          name: 'Earth (Replacement Dimension)',
        },
      },
    ],
  },
  shoppingCart: {
    __typename: 'ShoppingCart',
    id: btoa('ShoppingCart:1'),
    totalPrice: 10,
    numActionFigures: 1,
  },
};

This test is very similar to the one we created for the increaseChosenQuantity resolver, but in this case the cache starts with an action figure that has already been selected by the user. Also we added two more tests to make sure that we will not decrease the quantities and the price to less than 0.

Get character

Finally, let's add a test for the last resolver: getCharacter. Create a new file resolvers/get-character.resolver.test.ts and paste the contents below:

import { InMemoryCache, IntrospectionFragmentMatcher } from 'apollo-cache-inmemory';
import ApolloClient from 'apollo-client';
import fragmentData from '../generated/fragment-matcher.json';
import getCharacter from './get-character.resolver';
import { GetCharacterQuery, GetCharacterDocument } from '../generated/graphql';

describe('Add To Cart Resolver', () => {
  let cache: InMemoryCache;
  let client: ApolloClient<any>;

  beforeEach(() => {
    // Create mock fragment matcher
    const fragmentMatcher = new IntrospectionFragmentMatcher({
      introspectionQueryResultData: fragmentData,
    });

    // Create mock client and cache
    cache = new InMemoryCache({ addTypename: false, fragmentMatcher, freezeResults: true });
    client = new ApolloClient({
      cache,
      resolvers: { Query: { getCharacter } }, // Resolver we want to test
      assumeImmutableResults: true,
    });

    // Initialize the cache with the desired state
    cache.writeData({ data: mockData });
  });

  it('should retrieve a character', async () => {
    const result = await client.query<GetCharacterQuery>({
      query: GetCharacterDocument,
      variables: { id: '1' },
    });
    expect(result.data.getCharacter?.id).toBe('1');
    expect(result.data.getCharacter?.name).toBe('Rick Sanchez');
  });
});

const mockData = {
  characters: {
    results: [
      {
        id: '1',
        __typename: 'Character',
        name: 'Rick Sanchez',
        species: 'Human',
        image: 'https://rickandmortyapi.com/api/character/avatar/1.jpeg',
        chosenQuantity: 1,
        unitPrice: 10,
        origin: {
          id: '1',
          __typename: 'Location',
          name: 'Earth (C-137)',
        },
        location: {
          id: '20',
          __typename: 'Location',
          name: 'Earth (Replacement Dimension)',
        },
      },
    ],
  },
};

This test just runs the query through the Apollo and checks the result.

Testing the components

Now let's begin testing the components themselves.

App component

First let's begin with the App component. Create the file: components/app/app.test.tsx and paste the contents below:

import React from 'react';
import { shallow } from 'enzyme';
import App from './app';

describe('App Component', () => {
  it('should mount', () => {
    const wrapper = shallow(<App />);
    expect(wrapper).toBeTruthy();
  });
});

This test is just a smoke test to see if anything will break if we mount this component. Since this component doesn't do much else besides instating other components, just this smoke test is enough.

Character data component

Now let's also create a smoke test fo the CharacterData component in the file: components/character-data/character-data.test.tsx:

import React from 'react';
import { shallow } from 'enzyme';
import CharacterData from './character-data';

describe('Character Data', () => {
  it('should mount', () => {
    const wrapper = shallow(<CharacterData character={mockCharacter} />);
    expect(wrapper).toBeTruthy();
  });
});

const mockCharacter: any = {
  id: '1',
  __typename: 'Character',
  name: 'Rick Sanchez',
  species: 'Human',
  image: 'https://rickandmortyapi.com/api/character/avatar/1.jpeg',
  chosenQuantity: 1,
  unitPrice: 10,
  origin: {
    id: '1',
    __typename: 'Location',
    name: 'Earth (C-137)',
  },
  location: {
    id: '20',
    __typename: 'Location',
    name: 'Earth (Replacement Dimension)',
  },
};

In both tests above, we are using Enzyme's shallow. By using it, we are telling Enzyme that we just want to mount the top level component. It can and will ignore all sub-components. This is why we don't have to bother on creating mocks for the children of these two components.

The Apollo Mocked Provider

For the next components that we will test we will need the ApolloMockedProvider to simulate graphql queries and mutations. The ApolloMockedProvider is available on a separate package: yarn add -D @apollo/react-testing.

Character table component

Now, let's create a new test for the CharacterTable component. Since it contains a graphql query, we will need to use the MockedProvider to simulate the graphql elements.

To start, update the CharacterTable component in the components/character-table/character-table.tsx file with the content below. We've added a few ids to the components, so it is easier to query for them in the tests:

// Query state management
if (loading) {
  return <CircularProgress id='progress' />;
} else if (error) {
  return (
    <Typography variant='h5' id='error-msg'>
      Error retrieving data, please reload the page to try again.
    </Typography>
  );
} else if (!data || !data.characters || !data.characters.results) {
  return (
    <Typography variant='h5' id='no-data-msg'>
      No data available, please reload the page to try again.
    </Typography>
  );
}

Now create the file components/character-table/character-table.spec.tsx and paste the content below:

import React from 'react';
import { mount, ReactWrapper } from 'enzyme';
import CharacterTable from './character-table';
import { MockedProvider, wait } from '@apollo/react-testing';
import { act } from 'react-dom/test-utils';
import { GetCharactersDocument } from '../../generated/graphql';

jest.mock('../character-data/character-data', () => ({
  __esModule: true,
  default: function CharacterData() {
    return <tr />;
  },
}));

describe('Character Table', () => {
  it('should show a spinner when loading the data', async () => {
    let wrapper;
    await act(async () => {
      wrapper = mount(
        <MockedProvider addTypename={false} mocks={[]} resolvers={{}}>
          <CharacterTable />
        </MockedProvider>
      );
    });

    expect(wrapper).toBeTruthy();
    expect(wrapper).toContainMatchingElement('#progress');
  });

  it('should successfully display the character data', async () => {
    let wrapper: ReactWrapper;
    await act(async () => {
      // Mount the component
      wrapper = mount(
        <MockedProvider addTypename={false} mocks={[mockCharacters]} resolvers={{}}>
          <CharacterTable />
        </MockedProvider>
      );

      // Wait until the query is resolved
      await wait(0);
      wrapper.update();
    });

    expect(wrapper!).toContainMatchingElement('CharacterData');
  });

  it('should handle an error', async () => {
    let wrapper: ReactWrapper;

    await act(async () => {
      wrapper = mount(
        <MockedProvider addTypename={false} mocks={[mockWithError]} resolvers={{}}>
          <CharacterTable />
        </MockedProvider>
      );

      await wait(0);
      wrapper.update();
    });

    expect(wrapper!).toContainMatchingElement('#error-msg');
  });

  it('should handle when there is no data', async () => {
    let wrapper: ReactWrapper;

    await act(async () => {
      wrapper = mount(
        <MockedProvider addTypename={false} mocks={[emptyMock]} resolvers={{}}>
          <CharacterTable />
        </MockedProvider>
      );

      await wait(0);
      wrapper.update();
    });

    expect(wrapper!).toContainMatchingElement('#no-data-msg');
  });
});

const mockCharacters = {
  request: { query: GetCharactersDocument },
  result: {
    data: {
      characters: {
        __typename: 'Characters',
        results: [
          {
            id: '1',
            __typename: 'Character',
            name: 'Rick Sanchez',
            image: 'https://rickandmortyapi.com/api/character/avatar/1.jpeg',
            species: 'Human',
            chosenQuantity: 0,
            unitPrice: 0,
            origin: {
              id: '1',
              __typename: 'Location',
              name: 'Earth (C-137)',
            },
            location: {
              id: '20',
              __typename: 'Location',
              name: 'Earth (Replacement Dimension)',
            },
          },
          {
            id: '2',
            __typename: 'Character',
            name: 'Morty Smith',
            image: 'https://rickandmortyapi.com/api/character/avatar/2.jpeg',
            species: 'Human',
            chosenQuantity: 0,
            unitPrice: 0,
            origin: {
              id: '1',
              __typename: 'Location',
              name: 'Earth (C-137)',
            },
            location: {
              id: '20',
              __typename: 'Location',
              name: 'Earth (Replacement Dimension)',
            },
          },
        ],
      },
    },
  },
};

const mockWithError = {
  request: { query: GetCharactersDocument },
  error: new Error('Network Error'),
};

const emptyMock = {
  request: { query: GetCharactersDocument },
  result: {
    data: {
      characters: null,
    },
  },
};

There is quite a bit going on in this file, so let's break it down:

Test setup

First we created a mock of the CharacterData component, to make sure that we are testing the CharacterTable component in isolation (it is important to do this, because we are using mount instead of shallow, this way the whole component tree will be mounted).

Notice that the mock itself contains a default property which returns an functional component, this is because the CharacterData component is exported as the module default (export default function CharacterData), so we mock this by using the default parameter.

Should show a spinner when loading the data

Our first test checks if we show a spinner while loading the data from the graphql server. We do this, by mounting the whole component wrapped by the MockedProvider. Notice that we used mount instead of shallow, this is because the shallow function would only mount the first level component, which in this case is the MockedProvider, so we use mount to mount the whole component tree.

In this test, we don't have to pass any mocks to it, because we are not waiting for them to be resolved. We just want to see if the spinner will be shown when the query is loading.

Should successfully display the character data

In this test we check if we display the CharacterData components if our data loads successfully (keep in mind that this is not the real CharacterData component, but rather our mock). In order to do this, we had to configure a mock which contains the expected input and output data that is handled by the Apollo graphql.

Here we also use the wait function make sure our mock resolves so we can make assertions, otherwise we would only see the loading spinner.

Other tests

We have two more tests, one that checks if we can gracefully handle an error and the other when there is no data available (notice that the error mock has an error parameter instead of a result parameter).

At the end of the file, we have our mocks. In here, the same rule we applied with resolvers is valid: all of the fields that you requested in a query or a mutation must be returned in the mock. If a single field is missing, Apollo will throw an error.

You can take a look at Apollo's official documentation if you want to know more about the tests.

Note: in this test suite it is very important to set the resolver param in the MockedProvider, even if it is just an empty object. This is because our query has two @client fields (chosenQuantity and unitPrice) and if we don't set it, the MockedProvider will always throw a ApolloError: Network error: No more mocked responses for the query: query GetCharacters error.

Note 2: in some tests we need to use the act function to make sure our component's state is correct before making any assertions.

Character quantity component

In this component, we would like to test that a mutation to increase or decrease the character's quantity is called whenever we click one of the buttons. First let's add an id property to both so that we can test them more easily. Change the components/character-quantity/character-quantity.tsx file:

<IconButton color='primary' disabled={props.chosenQuantity <= 0} onClick={onDecreaseQty} id='decrease-btn'>
  <ChevronLeftIcon />
</IconButton>
<Typography>{props.chosenQuantity}</Typography>
<IconButton color='primary' onClick={onIncreaseQty} id='increase-btn'>
  <ChevronRightIcon />
</IconButton>

Now, create the file: components/character-quantity/character-quantity.test.tsx and paste the contents below:

import React from 'react';
import { mount, ReactWrapper } from 'enzyme';
import CharacterQuantity from './character-quantity';
import { MockedProvider, wait } from '@apollo/react-testing';
import { act } from 'react-dom/test-utils';
import {
  IncreaseChosenQuantityDocument,
  DecreaseChosenQuantityDocument,
} from '../../generated/graphql';

describe('Character Quantity', () => {
  it('should mount', () => {
    const wrapper = mount(
      <MockedProvider addTypename={false} mocks={[]}>
        <CharacterQuantity characterId='1' chosenQuantity={0} />
      </MockedProvider>
    );
    expect(wrapper).toBeTruthy();
  });

  it('should call a mutation when increasing a character quantity', async () => {
    let wrapper: ReactWrapper;

    // Grapqhl mock
    const mockIncreaseQuantity = {
      request: { query: IncreaseChosenQuantityDocument, variables: { input: { id: '1' } } },
      result: jest.fn().mockReturnValue({ data: { increaseChosenQuantity: true } }),
    };

    await act(async () => {
      // Mount
      wrapper = mount(
        <MockedProvider addTypename={false} mocks={[mockIncreaseQuantity]}>
          <CharacterQuantity characterId='1' chosenQuantity={0} />
        </MockedProvider>
      );

      // Simulate button click
      wrapper
        .find('#increase-btn')
        .first()
        .simulate('click');

      // Wait until the mutation is called
      await wait(0);
    });

    // Check if the mutation was actually called.
    expect(mockIncreaseQuantity.result).toHaveBeenCalled();
  });

  it('should call a mutation when decreasing a character quantity', async () => {
    let wrapper: ReactWrapper;

    const mockDecreaseQuantity = {
      request: { query: DecreaseChosenQuantityDocument, variables: { input: { id: '1' } } },
      result: jest.fn().mockReturnValue({ data: { increaseChosenQuantity: true } }),
    };

    await act(async () => {
      wrapper = mount(
        <MockedProvider addTypename={false} mocks={[mockDecreaseQuantity]}>
          <CharacterQuantity characterId='1' chosenQuantity={2} />
        </MockedProvider>
      );

      wrapper
        .find('#decrease-btn')
        .first()
        .simulate('click');

      await wait(0);
    });

    expect(mockDecreaseQuantity.result).toHaveBeenCalled();
  });

  it('should disable the decrease quantity button when the character quantity is 0', () => {
    const wrapper = mount(
      <MockedProvider addTypename={false} mocks={[]}>
        <CharacterQuantity characterId='1' chosenQuantity={0} />
      </MockedProvider>
    );
    expect(wrapper).toBeTruthy();
    expect(
      wrapper
        .find('#decrease-btn')
        .first()
        .prop('disabled')
    ).toBe(true);
  });
});

Let's breakdown this test:

We've added a function as the result value of both mutations instead of plain objects. The Apollo MockedProvider supports either objects, functions and promises as the result property. This way we can test if the mutation was called.

Just like queries, mutations are also executed asynchronously, so we use the await wait(0); function (after we clicked on the increase or decrease button) to wait until our mutation has finished executing.

Shopping cart component

For this component, we are going to check if it appears when we have one or more action figures selected. To simplify our tests open the file components/shopping-cart-btn/shopping-cart-btn.tsx and add id param to the <Box /> that is returned when there are no action figures selected:

if (!data || data.shoppingCart.numActionFigures <= 0) {
  return <Box className={classes.root} id='empty-btn' />;
}

Let's also add an id param to the <Box /> that contains the actual button:

return (
  <Box className={classes.root} id='shopping-cart-btn'>
    {/* [...] */}
  </Box>
);

Now create a new file: components/shopping-cart-btn/shopping-cart-btn.test.tsx and paste the contents below:

import React from 'react';
import { act } from 'react-dom/test-utils';
import { GetShoppingCartDocument } from '../../generated/graphql';
import { mount, ReactWrapper } from 'enzyme';
import { MockedProvider, wait } from '@apollo/react-testing';
import ShoppingCartBtn from './shopping-cart-btn';

describe('Shopping Cart Btn', () => {
  it('should not show the button when there are 0 action figures selected', async () => {
    let wrapper: ReactWrapper;
    await act(async () => {
      wrapper = mount(
        <MockedProvider addTypename={false} mocks={[mockEmptyCart]}>
          <ShoppingCartBtn />
        </MockedProvider>
      );

      await wait(0);
      wrapper.update();
    });

    expect(wrapper!).toContainMatchingElement('#empty-btn');
    expect(wrapper!).not.toContainMatchingElement('#shopping-cart-btn');
  });

  it('should show the button when there is 1 or more action figures selected', async () => {
    let wrapper: ReactWrapper;

    await act(async () => {
      wrapper = mount(
        <MockedProvider addTypename={false} mocks={[mockShoppingCart]}>
          <ShoppingCartBtn />
        </MockedProvider>
      );

      await wait(0);
      wrapper.update();
    });

    expect(wrapper!).not.toContainMatchingElement('#empty-btn');
    expect(wrapper!).toContainMatchingElement('#shopping-cart-btn');
  });
});

const mockEmptyCart = {
  request: { query: GetShoppingCartDocument },
  result: {
    data: {
      shoppingCart: {
        __typename: 'ShoppingCart',
        id: btoa('ShoppingCart:1'),
        totalPrice: 0,
        numActionFigures: 0,
      },
    },
  },
};

const mockShoppingCart = {
  request: { query: GetShoppingCartDocument },
  result: {
    data: {
      shoppingCart: {
        __typename: 'ShoppingCart',
        id: btoa('ShoppingCart:1'),
        totalPrice: 10,
        numActionFigures: 1,
      },
    },
  },
};

This test is similar to the other ones we've written so far: we use await wait(0); to wait for the query execution, then we check if we are showing the results correctly.

Conclusion

You can now run all the tests by executing the command: yarn test --watchAll. If all goes well all of them should pass.

Use Apollo to Manage the App's Local State

Felipe Armoni — Sat, 22 Feb 2020 15:26:25 +0000

On this second part we will create and manage the local application state using the Apollo In Memory Cache. Our objective is to allow the user to choose how many action figures from the Rick and Morty show he wants to buy and display a checkout screen with the total price and the summary of the chosen items.

This tutorial builds on top of the code generated in the Part 1. You can get it here.

The complete code for the Part 2 is available in this repository and the website here: https://komyg.github.io/rm-shop-v2/.

Note: this tutorial assumes that you have a working knowledge of React and Typescript.

Getting Started

To begin, clone the repository that we used on the Part 1.

After you cloned the repository, run yarn install to download the necessary packages.

Creating a local schema

First we will create a local schema to extend the properties that we have on the Rick and Morty API and create new ones. To do this, create a new file called: local-schema.graphql inside the src folder and paste the code below:

type Query {
  shoppingCart: ShoppingCart!
}

type Mutation {
  increaseChosenQuantity(input: ChangeProductQuantity!): Boolean
  decreaseChosenQuantity(input: ChangeProductQuantity!): Boolean
}

extend type Character {
  chosenQuantity: Int!
  unitPrice: Int!
}

type ShoppingCart {
  id: ID!
  totalPrice: Int!
  numActionFigures: Int!
}

input ChangeProductQuantity {
  id: ID!
}

Here is the breakdown our local schema:

As with all Graphql schemas we have the two basic types: Query and Mutation.
Inside the Query type we added a shoppingCart query that will return a ShoppingCart object that is stored locally on the Apollo In Memory Cache.
We also added two mutations: increaseChosenQuantity and decreaseChosenQuantity. Both will change the quantity the user has chosen for an action figure and update the shopping cart.
We extended the Character type from the Rick and Morty API to add two extra fields: chosenQuantity and unitPrice that will only exist in our local state.
We created an input type called ChangeProductQuantity that will be used inside the mutations. Note that we could send the characterId directly to the mutation, but we created the input type to illustrate its use. Also, a query or mutation can only accept a scalar or an input types as its arguments. They do not support regular types.

Note: the exclamation mark (!) at the end of the types, indicates that they are obligatory, therefore they cannot be null or undefined.

Updating the Grapqhql Codegen config file

Update the codegen.yml file to include the local schema we just created. We are also going to add the fragment matcher generator, so that we can use fragments on our queries and mutations.

overwrite: true
schema: "https://rickandmortyapi.com/graphql"
documents: "src/**/*.graphql"
generates:
  src/generated/graphql.tsx:
    schema: "./src/local-schema.graphql" # Local Schema
    plugins:
      - "typescript"
      - "typescript-operations"
      - "typescript-react-apollo"
      - "fragment-matcher"

    # Add this to use hooks:
    config:
      withHooks: true

  # Fragment Matcher
  src/generated/fragment-matcher.json:
    schema: "./src/local-schema.graphql"
    plugins:
      - "fragment-matcher"

Creating an initial state

When our application loads, it is good to initialize Apollo's InMemoryCache with an initial state based on our local schema. To do this, let's add the initLocalCache function to the config/apollo-local-cache.ts file:

export function initLocalCache() {
  localCache.writeData({
    data: {
      shoppingCart: {
        __typename: 'ShoppingCart',
        id: btoa('ShoppingCart:1'),
        totalPrice: 0,
        numActionFigures: 0,
      },
    },
  });
}

Here we are initializing the ShoppingCart objet with default values. Also note that we using an ID pattern of [Typename]:[ID] encoded in base 64. You can use this or any other pattern you like for the ID's as long as they are always unique.

Also note that it if we chose not to initialize the ShoppingCart object, it would be better to set it as null instead of leaving it as undefined. This is to avoid errors when running the readQuery function on the Apollo's InMemoryCache. If the object we are querying is undefined, then the readQuery will throw an error, but if it is null, then it will return null without throwing an exception.

Initializing the ShoppingCart to null would look like this:

// Don't forget that in this tutorial we want to have the shoppingCart initialized, so don't copy and paste the code below
export function initLocalCache() {
  localCache.writeData({
    data: {
      shoppingCart: null,
  });
}

Now lets call the initLocalCache function after the Apollo Client has been initialized in the config/apollo-client.ts file:

export const apolloClient = new ApolloClient({
  link: ApolloLink.from([errorLink, httpLink]),
  connectToDevTools: process.env.NODE_ENV !== 'production',
  cache: localCache,
  assumeImmutableResults: true,
});

initLocalCache();

Creating resolvers

Resolvers are functions that will manage our local InMemoryCache, by reading data from it and writing data to it. If you are accustomed to Redux, the resolvers would be similar to the reducer functions, even though they are not required to be synchronous nor are the changes to the InMemoryCache required to be immutable, although we chose to use immutability in the Part 1 of this tutorial in return for performance improvements.

Type resolvers

Type resolvers are used to initialize the local fields of a remote type. In our case, we have extended the Character type with the chosenQuantity and unitPrice fields.

To start, create the src/resolvers folder. Then create the set-unit-price.resolver.ts file and copy the contents below:

import ApolloClient from 'apollo-client';
import { Character } from '../generated/graphql';
import { InMemoryCache } from 'apollo-cache-inmemory';

export default function setChosenQuantity(
  root: Character,
  variables: any,
  context: { cache: InMemoryCache; getCacheKey: any; client: ApolloClient<any> },
  info: any
) {
  switch (root.name) {
    case 'Rick Sanchez':
      return 10;

    case 'Morty Smith':
      return 10;

    default:
      return 5;
  }
}

This resolver will receive each character from the backend and assign it unit price based on the character's name.

Then, lets connect this resolver our client. To do this, create the file: config/apollo-resolvers.ts and paste the contents below:

import setUnitPrice from '../resolvers/set-unit-price.resolver';

export const localResolvers = {
  Character: {
    chosenQuantity: () => 0,
    unitPrice: setUnitPrice,
  },
};

Since the initial value for the chosenQuantity will always be 0, then we will just create a function that returns 0.

Then, add the localResolvers to our client config in: config/apollo-client.ts.

export const apolloClient = new ApolloClient({
  link: ApolloLink.from([errorLink, httpLink]),
  connectToDevTools: process.env.NODE_ENV !== 'production',
  cache: localCache,
  assumeImmutableResults: true,
  resolvers: localResolvers,
});

initLocalCache();

Creating local queries

Now we can create a new query that will return the ShoppingCart object. To do this, create a new file called: graphql/get-shopping-cart.query.graphql and paste the contents below:

query GetShoppingCart {
  shoppingCart @client {
    id
    __typename
    totalPrice
    numActionFigures
  }
}

Now run the yarn gen-graphql command to generate its types. Notice that we can get the ShoppingCart without having to create a resolver, because the ShoppingCart object is a direct child of the root query.

Mutation resolvers

Now we are going to create mutations that will handle increasing and decreasing the quantity of a Character. First we should create a graphql file that will describe the mutation. Create the file: graphql/increase-chosen-quantity.mutation.graphql and paste the contents below:

mutation IncreaseChosenQuantity($input: ChangeProductQuantity!) {
  increaseChosenQuantity(input: $input) @client
}

Here we are using the @client annotation to indicate that this mutation should be ran locally on the InMemoryCache.

Also create another file: graphql/decrease-chosen-quantity.mutation.graphql and paste the contents below:

mutation DecreaseChosenQuantity($input: ChangeProductQuantity!) {
  decreaseChosenQuantity(input: $input) @client
}

Finally, let's also create a fragment that will be useful to retrieve a single Character directly from the cache. In Graphql a fragment is a pice of code that can be reused in queries and mutations. It can also be used to retrieve and update data directly in the Apollo's InMemoryCache without having to go through the root query.

This means that through the fragment below, we can get a single Character using its __typename and id.

Note: here we should have used the character(id: ID) query that is available in the graphql server, but I preferred to do this locally to demonstrate how it is done.

Create the graphql/character-data.fragment.graphql file:

fragment characterData on Character {
  id
  __typename
  name
  unitPrice @client
  chosenQuantity @client
}

Now run the Graphql Code Gen command to update our generated files: yarn gen-graphql. Then update the config/apollo-local-cache.ts with the fragment matcher:

import { InMemoryCache, IntrospectionFragmentMatcher } from 'apollo-cache-inmemory';
import introspectionQueryResultData from '../generated/fragment-matcher.json';

export const localCache = new InMemoryCache({
  fragmentMatcher: new IntrospectionFragmentMatcher({ introspectionQueryResultData }),
  freezeResults: true,
});

export function initLocalCache() {
  localCache.writeData({
    data: {
      shoppingCart: {
        __typename: 'ShoppingCart',
        id: btoa('ShoppingCart:1'),
        totalPrice: 0,
        numActionFigures: 0,
      },
    },
  });
}

Now let's create the resolvers themselves. First create the resolvers/increase-chosen-quantity.resolver.ts:

import ApolloClient from 'apollo-client';
import { InMemoryCache } from 'apollo-cache-inmemory';
import {
  CharacterDataFragment,
  CharacterDataFragmentDoc,
  IncreaseChosenQuantityMutationVariables,
  GetShoppingCartQuery,
  GetShoppingCartDocument,
} from '../generated/graphql';

export default function increaseChosenQuantity(
  root: any,
  variables: IncreaseChosenQuantityMutationVariables,
  context: { cache: InMemoryCache; getCacheKey: any; client: ApolloClient<any> },
  info: any
) {
  const character = getCharacterFromCache(variables.input.id, context.cache, context.getCacheKey);
  if (!character) {
    return false;
  }

  updateCharacter(character, context.cache, context.getCacheKey);
  updateShoppingCart(character, context.cache);

  return true;
}

function getCharacterFromCache(id: string, cache: InMemoryCache, getCacheKey: any) {
  return cache.readFragment<CharacterDataFragment>({
    fragment: CharacterDataFragmentDoc,
    id: getCacheKey({ id, __typename: 'Character' }),
  });
}

function updateCharacter(character: CharacterDataFragment, cache: InMemoryCache, getCacheKey: any) {
  cache.writeFragment<CharacterDataFragment>({
    fragment: CharacterDataFragmentDoc,
    id: getCacheKey({ id: character.id, __typename: 'Character' }),
    data: {
      ...character,
      chosenQuantity: character.chosenQuantity + 1,
    },
  });
}

function updateShoppingCart(character: CharacterDataFragment, cache: InMemoryCache) {
  const shoppingCart = getShoppingCart(cache);
  if (!shoppingCart) {
    return false;
  }

  cache.writeQuery<GetShoppingCartQuery>({
    query: GetShoppingCartDocument,
    data: {
      shoppingCart: {
        ...shoppingCart,
        numActionFigures: shoppingCart.numActionFigures + 1,
        totalPrice: shoppingCart.totalPrice + character.unitPrice,
      },
    },
  });
}

function getShoppingCart(cache: InMemoryCache) {
  const query = cache.readQuery<GetShoppingCartQuery>({
    query: GetShoppingCartDocument,
  });

  return query?.shoppingCart;
}

There is quite a bit happening here:

First we have the getCharacterFromCache function that retrieves a Character from the cache using the CharacterData fragment. This way we can retrieve the character directly, instead of having to go through the root query.
Then we have the updateCharacter function that increases the chosen quantity for this character by one. Notice that we are using the same CharacterData fragment to update the cache and that we are not updating the character directly, instead we are using the spread operator to update the cache with a copy of the original Character object. We've done this, because we decided to use immutable objects.
Then we update the ShoppingCart, by using the GetShoppingCartQuery to get the current state of the ShoppingCart and update the number of chosen Characters and the total price. Here we can use a query to retrieve the ShoppingCart, because it is a child of the root query, so we can get it directly.
When using fragments, we use the getCacheKey function to get an object's cache key. By default, the Apollo Client stores the data in a de-normalized fashion, so that we can use fragments and the cache key to access any object directly. Usually each cache key is composed as __typename:id, but it is a good practice to use the getCacheKey function in case you want to use a custom function to create the cache keys.
Notice that we are using the readQuery function to retrieve the current state of the ShoppingCart. We can do this, because we have set the initial state for the shopping cart, however if we had not set it, then this function would throw an exception the first time it ran, because its result would be undefined. If you do not want to set a definite state for a cache object, then it is good to set its initial state as null, instead of leaving it as undefined. This way, when you execute the readQuery function it will not throw an exception.
It is also worth mentioning, that we could use the client.query function instead of the cache.readQuery, this way we would not have to worry about the ShoppingCart being undefined, because the client.query function does not throw an error if the object it wants to retrieve is undefined. However the cache.readQuery is faster and it is also synchronous (which is useful in this context).
It is also worth mentioning that whenever we write data to the InMemoryCache using either the writeQuery or the writeFragment functions, than only the fields that are specified in the query or the fragment are updated, all other fields are ignored. So we wouldn't be able to update a character's image by using the characterData fragment, because the image parameter is not specified on it.

Now we will create a new resolver to decrease a Character chosen quantity. Please create the file: resolvers/decrease-chosen-quantity.resolver.ts and copy and paste the contents below:

import ApolloClient from 'apollo-client';
import { InMemoryCache } from 'apollo-cache-inmemory';
import {
  CharacterDataFragment,
  CharacterDataFragmentDoc,
  IncreaseChosenQuantityMutationVariables,
  GetShoppingCartQuery,
  GetShoppingCartDocument,
} from '../generated/graphql';

export default function decreaseChosenQuantity(
  root: any,
  variables: IncreaseChosenQuantityMutationVariables,
  context: { cache: InMemoryCache; getCacheKey: any; client: ApolloClient<any> },
  info: any
) {
  const character = getCharacterFromCache(variables.input.id, context.cache, context.getCacheKey);
  if (!character) {
    return false;
  }

  updateCharacter(character, context.cache, context.getCacheKey);
  updateShoppingCart(character, context.cache);

  return true;
}

function getCharacterFromCache(id: string, cache: InMemoryCache, getCacheKey: any) {
  return cache.readFragment<CharacterDataFragment>({
    fragment: CharacterDataFragmentDoc,
    id: getCacheKey({ id, __typename: 'Character' }),
  });
}

function updateCharacter(character: CharacterDataFragment, cache: InMemoryCache, getCacheKey: any) {
  let quantity = character.chosenQuantity - 1;
  if (quantity < 0) {
    quantity = 0;
  }

  cache.writeFragment<CharacterDataFragment>({
    fragment: CharacterDataFragmentDoc,
    id: getCacheKey({ id: character.id, __typename: 'Character' }),
    data: {
      ...character,
      chosenQuantity: quantity,
    },
  });
}

function updateShoppingCart(character: CharacterDataFragment, cache: InMemoryCache) {
  const shoppingCart = getShoppingCart(cache);
  if (!shoppingCart) {
    return false;
  }

  let quantity = shoppingCart.numActionFigures - 1;
  if (quantity < 0) {
    quantity = 0;
  }

  let price = shoppingCart.totalPrice - character.unitPrice;
  if (price < 0) {
    price = 0;
  }

  cache.writeQuery<GetShoppingCartQuery>({
    query: GetShoppingCartDocument,
    data: {
      shoppingCart: {
        ...shoppingCart,
        numActionFigures: quantity,
        totalPrice: price,
      },
    },
  });
}

function getShoppingCart(cache: InMemoryCache) {
  const query = cache.readQuery<GetShoppingCartQuery>({
    query: GetShoppingCartDocument,
  });

  return query?.shoppingCart;
}

This resolver is very similar to the other one, with the exception that we do not allow the quantities and the total price to be less than 0.

Finally let's connect these two resolvers to the Apollo client, by updating the config/apollo-resolvers.ts file:

import setUnitPrice from '../resolvers/set-unit-price.resolver';
import increaseChosenQuantity from '../resolvers/increase-chosen-quantity.resolver';
import decreaseChosenQuantity from '../resolvers/decrease-chosen-quantity.resolver';

export const localResolvers = {
  Mutations: {
    increaseChosenQuantity,
    decreaseChosenQuantity,
  },
  Character: {
    chosenQuantity: () => 0,
    unitPrice: setUnitPrice,
  },
};

Query resolvers

Technically we won't be needing any query resolvers for this app, but I think that it might be useful to do an example. So we are going to create a resolver that will return the data available for a Character.

Note that in a real project we should use the character(id: ID) query that is already available from the server instead of creating a new query.

To begin, update the Query type in our local schema:

type Query {
  shoppingCart: ShoppingCart!
  getCharacter(id: ID!): Character
}

Now, create a new file called: graphql/get-character.query.graphql and paste the contents below:

query GetCharacter($id: ID!) {
  getCharacter(id: $id) @client {
    ...characterData
  }
}

Now re-generate the graphql files with the command: yarn gen-graphql.

For the resolver itself, create a new file called: resolvers/get-character.resolver.ts:

import { InMemoryCache } from 'apollo-cache-inmemory';
import ApolloClient from 'apollo-client';
import {
  CharacterDataFragmentDoc,
  CharacterDataFragment,
  GetCharacterQueryVariables,
} from '../generated/graphql';

export default function getCharacter(
  root: any,
  variables: GetCharacterQueryVariables,
  context: { cache: InMemoryCache; getCacheKey: any; client: ApolloClient<any> },
  info: any
) {
  return context.cache.readFragment<CharacterDataFragment>({
    fragment: CharacterDataFragmentDoc,
    id: context.getCacheKey({ id: variables.id, __typename: 'Character' }),
  });
}

Finally let's connect this new resolver to the Apollo client by updating the config/apollo-resolvers.ts file:

import setUnitPrice from '../resolvers/set-unit-price.resolver';
import increaseChosenQuantity from '../resolvers/increase-chosen-quantity.resolver';
import decreaseChosenQuantity from '../resolvers/decrease-chosen-quantity.resolver';
import getCharacter from '../resolvers/get-character.resolver';

export const localResolvers = {
  Query: {
    getCharacter,
  },
  Mutation: {
    increaseChosenQuantity,
    decreaseChosenQuantity,
  },
  Character: {
    chosenQuantity: () => 0,
    unitPrice: setUnitPrice,
  },
};

Updating our components

Now that we have created our mutations and resolvers we will update our components to use them. First let's update our GetCharactersQuery to include our new local fields. Open the graphql/get-characters.query.graphql file and paste the contents below:

query GetCharacters {
  characters {
    __typename
    results {
      id
      __typename
      name
      image
      species
      chosenQuantity @client
      unitPrice @client
      origin {
        id
        __typename
        name
      }
      location {
        id
        __typename
        name
      }
    }
  }
}

Here we added the chosenQuantity and unitPrice fields with the @client annotation to tell Apollo that these fields are used only on the client.

Don't forget to regenerate our graphql types by running the yarn gen-graphql command on your console.

Now let's update our table to add these new fields. First open the components/character-table/character-table.tsx file and add two more columns to our table, one for the unit price and the other for the chosen quantity:

// Display the data
return (
  <TableContainer component={Paper}>
    <Table>
      <TableHead>
        <TableRow>
          <TableCell>
            <strong>Name</strong>
          </TableCell>
          <TableCell>
            <strong>Species</strong>
          </TableCell>
          <TableCell>
            <strong>Origin</strong>
          </TableCell>
          <TableCell>
            <strong>Location</strong>
          </TableCell>
          <TableCell>
            <strong>Price</strong>
          </TableCell>
          <TableCell>
            <strong>Quantity</strong>
          </TableCell>
        </TableRow>
      </TableHead>
      <TableBody>
        {data.characters.results.map(character => (
          <CharacterData character={character} key={character?.id!} />
        ))}
      </TableBody>
    </Table>
  </TableContainer>
);
);

Now we are going to create a new component to handle the user's choices. First add the Material UI Icons package: yarn add @material-ui/icons. Then create the file: components/character-quantity/character-quantity.tsx and paste the contents below:

import React, { ReactElement, useCallback } from 'react';
import { Box, IconButton, Typography } from '@material-ui/core';
import ChevronLeftIcon from '@material-ui/icons/ChevronLeft';
import ChevronRightIcon from '@material-ui/icons/ChevronRight';
import {
  useIncreaseChosenQuantityMutation,
  useDecreaseChosenQuantityMutation,
} from '../../generated/graphql';

interface Props {
  characterId: string;
  chosenQuantity: number;
}

export default function CharacterQuantity(props: Props): ReactElement {
  // Mutation Hooks
  const [increaseQty] = useIncreaseChosenQuantityMutation({
    variables: { input: { id: props.characterId } },
  });
  const [decreaseQty] = useDecreaseChosenQuantityMutation();

  // Callbacks
  const onIncreaseQty = useCallback(() => {
    increaseQty();
  }, [increaseQty]);
  const onDecreaseQty = useCallback(() => {
    decreaseQty({ variables: { input: { id: props.characterId } } });
  }, [props.characterId, decreaseQty]);

  return (
    <Box display='flex' alignItems='center'>
      <IconButton color='primary' disabled={props.chosenQuantity <= 0} onClick={onDecreaseQty}>
        <ChevronLeftIcon />
      </IconButton>
      <Typography>{props.chosenQuantity}</Typography>
      <IconButton color='primary' onClick={onIncreaseQty}>
        <ChevronRightIcon />
      </IconButton>
    </Box>
  );
}

In this component we are using two hooks to instantiate our mutations and then we are using two callbacks to call them whenever the user clicks on the increase or decrease quantity buttons.

You will notice that we've set the input for the useIncreaseChosenQuantityMutation when it was first instantiated and that we've set the input for the useDecreaseChosenQuantityMutation on the callback. Both options will work in this context, but it is worth saying that the input defined on the first mutation is static, and the input defined on the second mutation is dynamic. So, if we were working with a form for example, then we should have chosen to set the mutation's input when it is called not when it is first instantiated, otherwise it will always be called with our form's initial values.

Also there is no need to call another query here to get the character's chosen quantity, because this value already comes from the query we made in the CharacterTable component and it will be automatically updated by Apollo and passed down to this component when we fire the mutations.

Now open the file: components/character-data/character-data.tsx and include our new fields:

export default function CharacterData(props: Props): ReactElement {
  const classes = useStyles();

  return (
    <TableRow>
      <TableCell className={classes.nameTableCell}>
        <Box>
          <img src={props.character?.image!} alt='' className={classes.characterImg} />
        </Box>
        <Typography variant='body2' className={classes.characterName}>
          {props.character?.name}
        </Typography>
      </TableCell>
      <TableCell>{props.character?.species}</TableCell>
      <TableCell>{props.character?.origin?.name}</TableCell>
      <TableCell>{props.character?.location?.name}</TableCell>
      <TableCell>{props.character?.unitPrice}</TableCell>
      <TableCell>
        <CharacterQuantity
          characterId={props.character?.id!}
          chosenQuantity={props.character?.chosenQuantity!}
        />
      </TableCell>
    </TableRow>
  );
}

Now run our project using the yarn start command. You should see the unit price we set for each character (Rick and Morty should have a higher price than the others) and you should be able to increase and decrease each character's chosen quantity.

The Shopping Cart

Now let's add a shopping cart component that will show the total price and the total number of action figures that were chosen by the user. To do this, create a new component: components/shopping-cart-btn/shopping-cart-btn.tsx and paste the content below:

import React, { ReactElement } from 'react';
import { Fab, Box, makeStyles, createStyles, Theme, Typography } from '@material-ui/core';
import { useGetShoppingCartQuery } from '../../generated/graphql';
import ShoppingCartIcon from '@material-ui/icons/ShoppingCart';

const useStyles = makeStyles((theme: Theme) =>
  createStyles({
    root: {
      position: 'fixed',
      bottom: theme.spacing(4),
    },
    quantityText: {
      position: 'absolute',
      top: '4px',
      left: '50px',
      color: 'white',
    },
    btnElement: {
      padding: theme.spacing(1),
    },
  })
);

export default function ShoppingCartBtn(): ReactElement {
  const classes = useStyles();
  const { data } = useGetShoppingCartQuery();

  if (!data || data.shoppingCart.numActionFigures <= 0) {
    return <Box className={classes.root} />;
  }

  return (
    <Box className={classes.root}>
      <Fab variant='extended' color='primary'>
        <Box>
          <ShoppingCartIcon className={classes.btnElement} />
          <Typography variant='caption' className={classes.quantityText}>
            {data.shoppingCart.numActionFigures}
          </Typography>
        </Box>

        <Typography className={classes.btnElement}>
          {formatPrice(data.shoppingCart.totalPrice)}
        </Typography>
      </Fab>
    </Box>
  );
}

function formatPrice(price: number) {
  return `US$ ${price.toFixed(2)}`;
}

In this component we are using the useGetShoppingCart query hook to get the number of action figures that the user selected and the total price. The state of the ShoppingCart is handled on the Apollo InMemoryCache and is updated whenever we increase or decrease the action figure's quantities by their respective resolvers. We are also hiding this component until the customer has chosen at least one action figure.

Notice that we didn't needed to create a resolver to get the shopping cart's state. That is because the shopping cart's state is available as a direct child of the root Query, therefore we can get it more easily.

Note: in a real project, this button would take the user to some kind of checkout screen in which he would be able to review and place his order.

Finally let's update our app component to contain our new button. To do this, open the components/app/app.tsx file and add the ShoppingCartBtn component:

export default function App(): ReactElement {
  const classes = useStyles();

  return (
    <Container className={classes.root}>
      <Box display='flex' justifyContent='center' alignContent='center'>
        <CharacterTable />
        <ShoppingCartBtn />
      </Box>
    </Container>
  );
}

Conclusion

If all goes well, when you run our app you should be able to increase and decrease the desired quantity of action figures and see the total number and total price of the chosen products.

Creating an App using React and Apollo Graphql

Felipe Armoni — Fri, 07 Feb 2020 19:20:42 +0000

In this first part we will build a table that will show the available action figures, using data from the Rick and Morty API.

Note: this tutorial assumes that you have a working knowledge of React and Typescript.

You can find the complete code in this repository and the website here: https://komyg.github.io/rm-shop-v1/.

Getting Started

To get started, create a new React App using the CRA - Create React App tool:

yarn create react-app rm-shop-v1 --template typescript

Material UI

To make our App prettier we will use the Material UI:

yarn add @material-ui/core

Apollo Graphql

Add the necessary packages from Apollo:

yarn add graphql apollo-client apollo-cache-inmemory apollo-link-http apollo-link-error apollo-link graphql-tag  apollo-cache apollo-utilities @apollo/react-hoc @apollo/react-components @apollo/react-hooks

Note: I chose not to use the Apollo Boost for this tutorial.

Creating the Apollo Client

Now that we've added all the necessary Apollo packages we have to create and initialize the Apollo Client. For this tutorial we are going to connect it to the Rick and Morty API. Click on this link to see the playground with the graphql schema and the available data.

Create a folder called config to place the configuration files for our Apollo Client.

Note: I've chosen to separate each configuration in its own file, because I believe it makes them more readable and clean, however you could use a single file as the Apollo documentation suggests.

Configuring Apollo HTTP Link

The Apollo HTTP link handles the connection between the client app and the Graphql server. Let's create a new config file called: apollo-http-link.ts and add the contents below:

import { HttpLink } from 'apollo-link-http';

export const httpLink = new HttpLink({
  uri: 'https://rickandmortyapi.com/graphql',
});

The uri param is the endpoint that contains the graphql API that we are using.

Configuring the Apollo Error Link

The Apollo Error Link receives and logs any errors that may occur in the Graphql calls. Create a new config file named: apollo-error-link.ts and paste the contents below:

import { onError } from 'apollo-link-error';

export const errorLink = onError(({ graphQLErrors, networkError, response, operation }) => {
  if (graphQLErrors) {
    for (const error of graphQLErrors) {
      console.error(
        `[GraphQL error]: Message: ${error.message}, Location: ${error.locations}, Path: ${error.path}`,
        operation,
        response
      );
    }
  }
  if (networkError) {
    console.error(`[Network error]: ${networkError}`, operation, response);
  }
});

Notice that the errors here are split into two kinds: Grapqhl Errors and Network Error. The first kind concerns errors that occur in queries and mutations, such as constraint errors while saving data, incorrect data formats, etc. The second kind concerns errors that occur in the network and on the POST requests made by the Apollo, such as timeouts or any error code >= 400.

If you have an error reporting tool like Sentry, this is a good place to add them.

Configuring the Local Cache

The InMemoryCache is a module that stores the results of the queries and mutations locally so that you don't have to go to the server twice to get the same results. It can also be used for the application state management as we will see in the next parts of this tutorial. For now, create a new file named apollo-local-cache.ts and paste these contents:

import { InMemoryCache } from 'apollo-cache-inmemory';

export const localCache = new InMemoryCache({
  freezeResults: true,
});

The current version of Apollo doesn't require that the cached data be immutable, but we can get a performance boost if we design our cache this way. The freezeResults parameter helps us make sure our data is immutable, by throwing an error if we try to change an existing object while running our app in development mode.

Configuring the Apollo Client

Now we will configure the Apollo Client itself and import the configurations we made above. To do this, first create a new file called: apollo-client.ts and then paste the contents below:

import { ApolloClient } from 'apollo-client';
import { ApolloLink } from 'apollo-link';
import { httpLink } from './apollo-http-link';
import { errorLink } from './apollo-error-link';
import { localCache } from './apollo-local-cache';

export const apolloClient = new ApolloClient({
  link: ApolloLink.from([errorLink, httpLink]),
  connectToDevTools: process.env.NODE_ENV !== 'production',
  cache: localCache,
  assumeImmutableResults: true,
});

There is a lot going on this file:

First we created the ApolloClient using its constructor and passed a configuration object to it.
The first parameter of the configuration is the ApolloLink. It works as a chain of Apollo Link Objects that will either:
- Receive the request, transform it and pass it forward.
- Receive the request and pass it forward as it is.
- Receive the request, execute it and return the result to the previous object in the chain.

In our case, we have just two links: the errorLink and the httpLink. Notice that the order here is important, because we want the errorLink to capture any errors that are returned by the httpLink, so the errorLink must come before it.

You can have as many links as you want, for example: link: ApolloLink.from([authLink, errorLink, timeoutLink, restLink, httpLink]). In this example, the authLink must come first, because it adds an Authorization header that is used to authenticate all requests. Then comes the errorLink to capture and log all the errors thrown further down the chain. Then we have the timeoutLink that will return an error if the requests made down the chain take longer than a specified period of time. Then we have the restLink that is used to make rest calls and finally we have the httpLink that handles the Graphql requests.

The second parameter in the configuration is the connectToDevTools. It is active only on non production environments and it allows the Apollo Dev Tools to work.
The third parameter is the InMemoryCache.
The last parameter is assumeImmutableResults: true, it tells the Apollo Client that we intend to make our cached data immutable for a performance gain. Please note that we have to enforce the immutability by ourselves, but the parameter freezeResults that we configured on the InMemoryCache will help us do this, by throwing an error if we try to change an immutable object while on development.

The Apollo Provider

Now that we have successfully configured the Apollo Client, we have to add the ApolloProvider so that all of our components can access it. To do this, we will change our index.tsx file to:

import { ApolloProvider } from '@apollo/react-hooks';
import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';
import { apolloClient } from './config/apollo-client';
import * as serviceWorker from './serviceWorker';

ReactDOM.render(
  <ApolloProvider client={apolloClient}>
    <App />
  </ApolloProvider>,
  document.getElementById('root')
);

serviceWorker.unregister();

Graphql Codegen

The Graphql Codegen is a tool that automatically generates typescript types and classes based on your Grapqhql Schema. It is very useful to ensure type safety.

Configuring the Grapqhl Codegen

The Grapqhl Codegen comes with a CLI tool that helps you create a configuration file. To use it follow these steps:

Install the CLI:

yarn add -D @graphql-codegen/cli

Execute the wizard:

yarn graphql-codegen init

Choose the following options:

Application built with React.
For this tutorial we will use the Rick and Morty Graphql API. Its endpoint is this one: https://rickandmortyapi.com/graphql.
Use the default value (src/**/*.graphql) for the fragment and operations.
Then pick the following plugins:
- TypeScript
- TypeScript Operations
- TypeScript React Apollo
- Introspection Fragment Matcher
Use the default value for the output (src/generated/graphql.tsx).
Answer no when it asks if you want to generate an introspection file.
Use the default value for the name of the config file (codegen.yml).
Type in gen-graphql when it asks the name of the script in the package.json that will be used to generate the graphql files.

After the wizard finishes, run yarn install to install all the necessary plugins added by the Grapqhl Code Gen.

Now, open your codegen.yml file and add the config param to tell the codegen that we want to use hooks. The final file looks like the one below:

overwrite: true
schema: "https://rickandmortyapi.com/graphql"
documents: "src/**/*.graphql"
generates:
  src/generated/graphql.tsx:
    plugins:
      - "typescript"
      - "typescript-operations"
      - "typescript-react-apollo"
      - "fragment-matcher"

    # Add this to use hooks:
    config:
      withHooks: true

Creating Our First Query

Now that we have added all necessary packages, let's create our first graphql query to retrieve all characters from the Rick and Morty API. To do this, create a folder called graphql inside our src folder. Next, create a new file called: get-characters.query.graphql and paste the contents below:

query GetCharacters {
  characters {
    __typename
    results {
      id
      __typename
      name
      image
      species
      origin {
        id
        __typename
        name
      }
      location {
        id
        __typename
        name
      }
    }
  }
}

Note: I have added the id and __typename parameters to our query, even though they are not necessary at this point in our tutorial. I did this, because we will use the id field later and because the Apollo Dev Tools needs to have both parameters to show what is in our cache.

Now run the Graphql Codegen to generate the typescript types:

yarn gen-graphql

If the command ran successfully, you should see that a graphql.tsx file was created inside our generated folder and that it contains our query.

Displaying the query data

Now that we have our first query, we would like to display its data as a table. To do this, create a new folder called src/components.

Creating the character table

Create a new folder: src/components/character-table and create the file: character-table.tsx inside it. This component will execute our query and display its data inside a table.

Copy and paste the code below into the character-table.tsx file:

import {
  CircularProgress,
  Paper,
  Table,
  TableBody,
  TableCell,
  TableContainer,
  TableHead,
  TableRow,
  Typography,
} from '@material-ui/core';
import React, { ReactElement } from 'react';
import { useGetCharactersQuery } from '../../generated/graphql';
import CharacterData from '../character-data/character-data';

interface Props {}

export default function CharacterTable(props: Props): ReactElement {
  // Use hook to retrieve data from the backend
  const { data, loading, error } = useGetCharactersQuery();

  // Query state management
  if (loading) {
    return <CircularProgress />;
  } else if (error) {
    return (
      <Typography variant='h5'>
        Error retrieving data, please reload the page to try again.
      </Typography>
    );
  } else if (!data || !data.characters || !data.characters.results) {
    return (
      <Typography variant='h5'>No data available, please reload the page to try again.</Typography>
    );
  }

  // Display the data
  return (
    <TableContainer component={Paper}>
      <Table>
        <TableHead>
          <TableRow>
            <TableCell>
              <strong>Name</strong>
            </TableCell>
            <TableCell>
              <strong>Species</strong>
            </TableCell>
            <TableCell>
              <strong>Origin</strong>
            </TableCell>
            <TableCell>
              <strong>Location</strong>
            </TableCell>
          </TableRow>
        </TableHead>
        <TableBody>
          {data.characters.results.map(character => (
            <CharacterData character={character} key={character?.id!} />
          ))}
        </TableBody>
      </Table>
    </TableContainer>
  );
}

As you can see there are a lot of things happening in this file:

First we use the useGetCharactersQuery hook. It executes our query as soon as the component finishes mounting. We have also destructured its output using: { data, loading, error }.
Then we have a state management code in which we display different outputs depending on the query state. For example, we show a progress spinner when the query is retrieving data from the server or we show an error message if something goes wrong or if no data is available.
Finally, if the query successfully retrieves the character data from the server, then we display it inside the <Table> element. Notice that we are mapping the array of characters that is returned by the query into a <CharacterData /> component that we will create shortly.
Also notice that we are passing a key attribute to the <CharacterData /> component. This is a good practice to improve React's rendering speed.

Creating the character data

Create a new folder: src/components/character-data and create the file: character-data.tsx inside it. This component will display our data as a table row.

Copy and paste the code below into the character-data.tsx file:

import React, { ReactElement } from 'react';
import { Character, Maybe } from '../../generated/graphql';
import {
  TableRow,
  TableCell,
  Box,
  createStyles,
  Theme,
  makeStyles,
  Typography,
} from '@material-ui/core';

interface Props {
  character: Maybe<Character | null>;
}

const useStyles = makeStyles((theme: Theme) =>
  createStyles({
    nameTableCell: {
      display: 'flex',
      alignItems: 'center',
    },
    characterImg: {
      maxHeight: '3rem',
      width: 'auto',
      borderRadius: '50%',
    },
    characterName: {
      paddingLeft: theme.spacing(2),
    },
  })
);

export default function CharacterData(props: Props): ReactElement {
  const classes = useStyles();

  return (
    <TableRow>
      <TableCell className={classes.nameTableCell}>
        <Box>
          <img src={props.character?.image!} alt='' className={classes.characterImg} />
        </Box>
        <Typography variant='body2' className={classes.characterName}>
          {props.character?.name}
        </Typography>
      </TableCell>
      <TableCell>{props.character?.species}</TableCell>
      <TableCell>{props.character?.origin?.name}</TableCell>
      <TableCell>{props.character?.location?.name}</TableCell>
    </TableRow>
  );
}

This component is pretty straight forward. But it is worth noticing that the data type that we are using on the character prop was generated by the Graphql Codegen. It indicates that the character might be null.

We are using the new Optional Chaining Operator (?.) to simplify our code. What it does is return undefined if the character property is also undefined or null instead of throwing an error.

And we are also using the Material UI styling tools that rely on jss.

Create a new app component

Finally let's create a new App component to display our data. To start, please delete the App.tsx, App.test.tsx and App.css files. Then create a new folder: components/app and create a new app.tsx file inside it.

Copy and paste the following code:

import React, { ReactElement } from 'react';
import { Container, Box, Theme, makeStyles, createStyles } from '@material-ui/core';
import CharacterTable from '../character-table/character-table';

const useStyles = makeStyles((theme: Theme) =>
  createStyles({
    root: {
      paddingTop: theme.spacing(2),
      paddingBottom: theme.spacing(2),
    },
  })
);

export default function App(): ReactElement {
  const classes = useStyles();

  return (
    <Container className={classes.root}>
      <Box display='flex' justifyContent='center' alignContent='center'>
        <CharacterTable />
      </Box>
    </Container>
  );
}

Notice that we are using the createStyles hook to avoid using css. (see: https://material-ui.com/customization/components/#overriding-styles-with-classes).

Update the index.tsx file

Now, update the index.tsx file to use our new App component:

import { ApolloProvider } from '@apollo/react-hooks';
import React from 'react';
import ReactDOM from 'react-dom';
import App from './components/app/app';
import { apolloClient } from './config/apollo-client';
import * as serviceWorker from './serviceWorker';

ReactDOM.render(
  <ApolloProvider client={apolloClient}>
    <App />
  </ApolloProvider>,
  document.getElementById('root')
);

serviceWorker.unregister();

Running our App

Now we have everything we need to run our App. Open a console and type yarn start to run the development server and open a browser in this address: http://localhost:3000.

If all goes well, you should see our table with the characters from Rick and Morty.