Undocumented option errorOnTimeout

[devopsix]

When a timeout has occured, options.errorOnTimeout is tested in order to determine if the command should error or not in mailosaurCommands.js, l. 161.

This option is not a property of the SearchOptions interface. But this interface has a suppressError property which seems to be unused.

I am wondering if that option is undocumented intentionally or if it should actually have been renamed in commit 76de346.

[Jon M]

Hi @devopsix

The suppressError functionality is only in use with the mailosaurGetMessage command (which uses the search command itself). This is because we had asks from customers to allow this command to support the concept of expecting a result not to be found for the given criteria.

The search commands themselves though do not require this functionality, as it should never timeout when searching.

[devopsix]

Are the provided types possibly not 100% in line with what the code actually does?

Calling the errorOnTimeout option “undocumented” may be slighty misleading as it actually is mentioned in How to test email and SMS with Cypress. But due to the types provided for cypress-mailosaur, in Typescript projects, IDE content assist features suggest something which is not actually working:

const serverId = Cypress.env('MAILOSAUR_SERVER_ID');

describe('mailosaurSearchMessages', async () => {
  it('fails', () => {
    cy.mailosaurSearchMessages(
      serverId,
      {sentTo: `nothing-ever-sent-to@${serverId}.mailosaur.com`},
      // IDE suggests suppressError.
      // But it will fail with “No matching messages found in time.” because suppressError is not tested in the command.
      {timeout: 500, suppressError: true}
    )
      .its('items')
      .should('have.length', 0);
  });

  it('succeeds', () => {
    cy.mailosaurSearchMessages(
      serverId,
      {sentTo: `nothing-ever-sent-to@${serverId}.mailosaur.com`},
      // Will succeed because errorOnTimeout is what is actually tested in mailosaurSearchMessages.
      // Have to use “@ts-ignore” here because errorOnTimeout is not a property of SearchOptions.
      // @ts-ignore
      {timeout: 500, errorOnTimeout: false}
    )
      .its('items')
      .should('have.length', 0);
  });
});

describe('mailosaurGetMessage', async () => {
  it('fails', () => {
    cy.mailosaurGetMessage(
      serverId,
      {sentTo: `nothing-ever-sent-to@${serverId}.mailosaur.com`},
      // @ts-ignore
      // If SearchOptions.suppressError was simply renamed to errorOnTimeout this would seem valid:
      {timeout: 500, errorOnTimeout: false}
      // But it will fail with “Cannot read properties of undefined (reading 'id')”.
      // The options arguments of mailosaurSearchMessages and mailosaurGetMessage should be typed differently
      // so that neither suppressError nor errorOnTimeout is suggested.
    )
      .its('items')
      .should('have.length', 0);
  });
});

[Jon M]

Good catch @devopsix, the supressError reference is a hang-over from a previous version, this is now fixed in version 2.5.2 of the client. The comments over this property also further clarifies that this is intended for use with mailosaurGetMessage too.

[devopsix]

@hippyhorse That's great, thank you very much!

When will 2.5.2 be available through npm? Currently, the most recent version found at npmjs.com seems to be 2.5.1.

Is it possible something has gone wrong with the 2.5.2 release build job?

[Jon M]

You're absolutely right, version 2.5.6 should now be live!