DEV Community: Robin Pellegrims

Testing a contact form with Cypress

Robin Pellegrims — Tue, 02 Aug 2022 00:00:00 +0000

Introduction

Many websites have a dedicated contact form that allows users to send a message to the website owner. Using Cypress, we can easily write automated tests to prevent regressions to these types of forms.

Use case

For this article, we'll use a contact form containing three fields:

Name
E-Mail
Message

Acceptance criteria

Before diving into writing the actual tests, it's usually a good idea to reflect on the acceptance criteria to determine what actually needs to be tested:

The contact form should be empty by default
The form can only be submitted if
- All form fields are filled in
- The e-mail address field contains a valid e-mail address
After the form has been successfully submitted
- The fields should be hidden
- A message should be shown saying the form was sent successfully
In case of an http error after submitting the form, an error message should be displayed and the fields should remain visible

Support functions

Based on these acceptance criteria, we can prepare some support functions to implement the desired checks and to make the actual test file more readable and maintainable. These functions can be added in the Cypress test file on top of your actual tests, or you could add them in specific support file.

Retrieving the fields DOM elements

Since our contact form already contains ids for each field, the field elements can easily be retrieved:

type ChainableInputElement = Cypress.Chainable<JQuery<HTMLInputElement>>;

export const getNameField = (): ChainableInputElement => cy.get('#field-Name');
export const getMailField = (): ChainableInputElement => cy.get('#field-Email');
export const getMessageField = (): ChainableInputElement =>
  cy.get('#field-Message');
export const getForm = () => cy.get('form');

The reason we explicitly define the return type for each of the query functions is that by default, cy.get returns a Chainable HTMLElement, which doesn't allow us to chain with other handy functions like type.

Filling out the form

We'll need to be able to fill out the form with some valid dummy values:

export const completeForm = () => {
  getNameField().type('John Doe');
  getMailField().type('john.doe@mail.com');
  getMessageField().type('This is my message');
};

Check validity of fields

The fields are all required so they might throw a validation error valueMissing. On top of that, the e-mail field might throw a typeMismatch validation error if the entered value is not a valid e-mail address.

export const assertValueMissing = (field: ChainableInputElement) =>
  assertValidity(field, { valueMissing: true });

export const assertTypeMismatch = (field: ChainableInputElement) =>
  assertValidity(field, { typeMismatch: true });

const assertValidity = (
  field: ChainableInputElement,
  expectedValidity: { valueMissing?: boolean; typeMismatch?: boolean }
) =>
  field.invoke('prop', 'validity').should('deep.include', {
    valueMissing: false,
    typeMismatch: false,
    ...expectedValidity,
  });

Form fields visibility

The following function verifies if the fields are visible or hidden:

export const assertFieldsVisible = (visible: boolean) =>
  cy.get('input').should(visible ? 'have.length.gt' : 'have.length', 0);

Mocking the api call

When we submit the form using a POST request in a Cypress test, we don't want to actually send the form data to the api. Instead, we can use intercept to mock the api call and return a specific response.

Note that we store the intercepted call using an alias so that we can easily check later if the data was submitted or not.

const submitAlias = 'submit';

export const mockResponseStatusCode = (statusCode: number) =>
  cy
    .intercept('POST', 'http://localhost:4200/api/contact', { statusCode })
    .as(submitAlias);

Checking that the form was submitted

To verify if the form data was submitted, the previously assigned alias can be used:

export const assertSubmitted = (submitted: boolean) =>
  cy.get(`@${submitAlias}`).should(submitted ? 'not.be.null' : 'be.null');

Submitting the form

There is only one button on the page, so we can just click the first button found to submit the form:

export const clickSubmitButton = () => cy.get('button').click();

Implementing the Cypress test

Now that we have all these support functions ready, we can easily implement the actual tests:

describe('contact', () => {
  beforeEach(() => cy.visit('/contact'));

  it('form fields should be empty by default', () =>
    [getNameField(), getMailField(), getMessageField()].forEach((field) =>
      field.should('be.empty')
    ));

  it('form fields should have errors for missing fields', () => {
    assertValueMissing(getNameField());
    assertValueMissing(getMailField());
    assertValueMissing(getMessageField());
  });

  it('email field should have an error for an incorrect email address', () => {
    getMailField().type('john.doe@');
    assertTypeMismatch(getMailField());
  });

  describe('when submitting an invalid form', () => {
    beforeEach(() => {
      mockResponseStatusCode(204);
      clickSubmitButton();
    });
    it('should not send a POST request to the APi', () =>
      assertSubmitted(false));
    it('should keep the fields visible', () => assertFieldsVisible(true));
  });

  describe('when submitting a valid form', () => {
    beforeEach(() => {
      completeForm();
      mockResponseStatusCode(204);
      clickSubmitButton();
    });
    it('should send a POST request to the APi', () => assertSubmitted(true));
    it('should display a success message', () =>
      getForm().should('contain', 'Message succesfully sent, thank you!'));
    it('should hide the form fields', () => assertFieldsVisible(false));
  });

  describe('when submitting a valid form returns an error response', () => {
    beforeEach(() => {
      completeForm();
      mockResponseStatusCode(400);
      clickSubmitButton();
    });
    it('should send a POST request to the APi', () => assertSubmitted(true));
    it('should display an error message', () =>
      getForm().should('contain', 'Something went wrong, try again later.'));
    it('should keep the fields visible', () => assertFieldsVisible(true));
  });
});

Summary

In this article, we demonstrated how to implement automated testing for a simple contact form using Cypress.

We first defined some acceptance criteria determining the requirements for the contact form. Based on these acceptance criteria, a number of support functions were implemented to keep the final test file more readable and maintainable. Finally, these support functions were used in the actual test file.

Make Angular Material dialogs type-safe

Robin Pellegrims — Mon, 27 Jun 2022 00:00:00 +0000

Introduction

Angular Material provides a MatDialogService that allows developers to easily integrate modal dialogs into their applications. If you're not familiar with Angular Material or its dialog service, check out the official documentation.

While this dialog service is very easy to use, the interaction between the MatDialogService and your dialog component isn't completely type-safe and could potentially lead to runtime issues.

Use case

Our use case is using Angular v13.3.8 and is based on this example in the official Angular Material documentation.

The dialog receives an input object representing a favorite animal:

export interface DialogData {
  animal: string;
}

It then displays the animals in a dialog and asks the user to cancel or approve:

After clicking one of the buttons, the dialog returns a boolean representing the button that was clicked.

Implementation

Parent component

// template
<button mat-button (click)="openDialog()">Open dialog</button>


@Component({
  selector: 'app-component',
  // template: see above
})
export class AppComponent {
  constructor(public dialog: MatDialog) {}

  openDialog() {
    this.dialog
      .open(DialogComponent, { data: { animal: 'panda' } })
      .afterClosed()
      .pipe(tap((result) => console.log(result === true)))
      .subscribe();
  }
}

Dialog component

// template
<h1 mat-dialog-title>Favorite Animal</h1>
<mat-dialog-content>
  <p>My favorite animal is "{{ data.animal }}".</p>
  <p>Do you approve?</p>
</mat-dialog-content>
<mat-dialog-actions>
  <button mat-button (click)="cancelClick()">Cancel</button>
  <button mat-button (click)="okClick()">Ok</button>
</mat-dialog-actions>


@Component({
  selector: 'example-dialog',
  // template: see above
})
export class DialogComponent {
  constructor(
    @Inject(MAT_DIALOG_DATA) public data: DialogData,
    public dialogRef: MatDialogRef<DialogComponent>
  ) {}

  cancelClick = () => this.dialogRef.close(false);
  okClick = () => this.dialogRef.close(true);
}

Type safety issues

While the dialog in our use case is currently working perfectly fine, the interaction between the parent and the dialog component is not completely type-safe.

Let's identify some possible issues that will still compile completely fine, but that would break at runtime.

Parent component

When opening the dialog, a typo could be made in the animal property name that is passed as the dialog data:

this.dialog.open(DialogComponent, { data: { annimal: 'panda' } });

The parent component receives an untyped result from the afterClosed operator that could be used in a wrong way:

this.dialog
  .open(DialogComponent, { data: { animal: 'panda' } })
  .afterClosed()
  // this will always log false, since result is a boolean
  .pipe(tap((result) => console.log(result === 'true')))
  .subscribe();

Dialog component

In the dialog component we might have forgotten about the correct type we were going to use and use a wrong type instead:

@Inject(MAT_DIALOG_DATA) public data: { favouriteAnimal: string }

The dialog should return a boolean value after closing, but nothing currently prevents us from passing anything else when closing the dialog:

this.dialogRef.close('cancel');

Parent-child type synchronization

There is no synchronization between the Data and Result types used in the parent component and the dialog component. This means the application will still compile when we use different types by mistake on both sides.

Adding generic params

A first step towards more type-safety would be to explicitly specify the types in the parent component when opening the dialog:

// parent component
this.dialog
  .open<DialogComponent, DialogData, boolean>(DialogComponent, {
    data: { animal: 'panda' },
  })
  .afterClosed()
  // result: boolean | undefined
  .pipe(tap((result) => console.log(result === true)))
  .subscribe();

In the dialog component, we can force the result type when injecting the MatDialogRef:

// dialog component
constructor(
  @Inject(MAT_DIALOG_DATA) public data: DialogData,
  public dialogRef: MatDialogRef<DialogComponent, boolean>
) {}

While these simple changes effectively force the developer to use correct dialog data and result objects, it still doesn't prevent using different Data/Result types in the parent and dialog component. It also has the drawback that the types need to be specified in both the parent and child component.

Using an abstract dialog component superclass

To increase type safety even further between the parent and dialog component and have a single source of truth for the dialog Data/Result types, a custom dialog service and abstract dialog component superclass can be created:

@Directive()
export abstract class StronglyTypedDialog<DialogData, DialogResult> {
  constructor(
    @Inject(MAT_DIALOG_DATA) public data: DialogData,
    public dialogRef: MatDialogRef<
      StronglyTypedDialog<DialogData, DialogResult>,
      DialogResult
    >
  ) {}
}

@Injectable({ providedIn: 'root' })
export class DialogService {
  constructor(public dialog: MatDialog) {}

  open = <DialogData, DialogResult>(
    component: ComponentType<StronglyTypedDialog<DialogData, DialogResult>>,
    config?: MatDialogConfig<DialogData>
  ): MatDialogRef<
    StronglyTypedDialog<DialogData, DialogResult>,
    DialogResult
  > => this.dialog.open(component, config);
}

Since the constructor has been moved to an abstract superclass, the dialog component can then be simplified like this:

@Component({
  selector: 'example-dialog',
  // template: unchanged, see above
})
export class DialogComponent extends StronglyTypedDialog<DialogData, boolean> {
  cancelClick = () => this.dialogRef.close(false);
  okClick = () => this.dialogRef.close(true);
}

The dialog can then be opened through this new DialogService instead of the regular MatDialog service:

@Component({
  selector: 'app-component',
  // template: unchanged, see above
})
export class AppComponent {
  constructor(public dialog: DialogService) {}

  openDialog() {
    this.dialog
      .open(DialogComponent, { data: { animal: 'panda' } })
      .afterClosed()
      // result: boolean | undefined
      .pipe(tap((result) => console.log(result === true)))
      .subscribe();
  }
}

This will achieve full type-safety on both the parent and dialog component while making the DialogComponent the single source of truth for the Data/Result types.

Summary

We explored multiple possible runtime issues when using Angular Material dialogs:

passing unexpected data into the dialog
returning unexpected results from the dialog to the parent component
using different data/result types in the parent and dialog component

Some of the issues can be addressed by adding generic params:

in the function call that opens the dialog
to the injected MatDialogRef in the dialog constructor

Finally, the open() method of the MatDialogService can be wrapped in a custom service that provides full type-safety and addresses all of the explored issues.