Cypress

Install

npm install --save-dev cypress @inboxical/cypress

Setup

1. Register the plugin in cypress.config.ts:

import { defineConfig } from 'cypress'
import { setupInboxical } from '@inboxical/cypress'

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      setupInboxical(on, config, {
        apiKey: process.env.INBOXICAL_API_KEY,
      })
      return config
    },
  },
})

Alternatively, set the key in cypress.env.json (add to .gitignore):

{
  "INBOXICAL_API_KEY": "ixk_live_..."
}

Full example

cypress/e2e/signup.cy.ts

describe('Signup email flow', () => {
  let inbox: { id: string; email: string }

  beforeEach(() => {
    cy.task('inboxicalCreateInbox', { name: 'signup-test' }).then((result) => {
      inbox = result as { id: string; email: string }
    })
  })

  afterEach(() => {
    cy.task('inboxicalDeleteInbox', inbox.id)
  })

  it('sends welcome email after signup', () => {
    cy.visit('/register')
    cy.get('[name=email]').type(inbox.email)
    cy.get('[name=password]').type('test-password-123')
    cy.get('[type=submit]').click()

    cy.url().should('include', '/dashboard')

    cy.task('inboxicalWaitForMessage', {
      inboxId: inbox.id,
      timeout: 30,
    }).then((message: any) => {
      expect(message.subject).to.equal('Welcome to MyApp!')
    })
  })
})

Extracting verification codes

it('completes verification with OTP from email', () => {
  cy.visit('/register')
  cy.get('[name=email]').type(inbox.email)
  cy.get('[name=password]').type('test-password-123')
  cy.get('[type=submit]').click()

  cy.task('inboxicalWaitForMessage', {
    inboxId: inbox.id,
    timeout: 30,
  }).then((message: any) => {
    cy.task('inboxicalExtractCode', { message }).then((code) => {
      cy.get('#verification-code').type(code as string)
      cy.get('#verify-button').click()
      cy.contains('Email verified').should('be.visible')
    })
  })
})

Tip

For custom code formats, pass a regex pattern string:

cy.task('inboxicalExtractCode', {
  message,
  pattern: 'token: ([A-Z0-9]{8})',
})

Available tasks

Task	Arguments	Returns
inboxicalCreateInbox	{ name?, domain? } or null	{ id, email }
inboxicalGetInbox	inboxId	Inbox object
inboxicalDeleteInbox	inboxId	null
inboxicalGetMessages	inboxId	Message[]
inboxicalGetLatestMessage	inboxId	Message object
inboxicalWaitForMessage	{ inboxId, timeout?, since? }	Message object
inboxicalGetMessage	messageId	Message object
inboxicalDeleteMessage	messageId	null
inboxicalExtractCode	{ message, pattern? }	string | null

Tips

• Set a higher Cypress timeout for long-poll tasks:

  cy.task('inboxicalWaitForMessage', { inboxId: inbox.id, timeout: 30 }, { timeout: 40_000 })

• Use afterEach to delete inboxes — keeps your dashboard clean
• Store the API key in CI as a secret, not in cypress.env.json