{"id":35159570,"url":"https://github.com/mailisk-app/cypress-mailisk","last_synced_at":"2026-04-11T16:09:42.852Z","repository":{"id":57959480,"uuid":"527213699","full_name":"mailisk-app/cypress-mailisk","owner":"mailisk-app","description":"Mailisk library for Cypress","archived":false,"fork":false,"pushed_at":"2026-02-09T17:10:31.000Z","size":111,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-02-09T20:54:05.457Z","etag":null,"topics":["cypress","cypress-plugin","email","email-testing","end-to-end-testing","qa","qatools","testing-tools"],"latest_commit_sha":null,"homepage":"https://docs.mailisk.com/guides/cypress","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mailisk-app.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-08-21T13:25:03.000Z","updated_at":"2026-02-09T17:08:31.000Z","dependencies_parsed_at":"2023-01-21T04:50:41.352Z","dependency_job_id":null,"html_url":"https://github.com/mailisk-app/cypress-mailisk","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/mailisk-app/cypress-mailisk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mailisk-app%2Fcypress-mailisk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mailisk-app%2Fcypress-mailisk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mailisk-app%2Fcypress-mailisk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mailisk-app%2Fcypress-mailisk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mailisk-app","download_url":"https://codeload.github.com/mailisk-app/cypress-mailisk/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mailisk-app%2Fcypress-mailisk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31686243,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-11T13:07:20.380Z","status":"ssl_error","status_checked_at":"2026-04-11T13:06:47.903Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cypress","cypress-plugin","email","email-testing","end-to-end-testing","qa","qatools","testing-tools"],"created_at":"2025-12-28T17:56:22.563Z","updated_at":"2026-04-11T16:09:42.847Z","avatar_url":"https://github.com/mailisk-app.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cypress-mailisk\n\nMailisk is an end-to-end email and SMS testing platform. It allows you to receive emails and SMS messages with code to automate tests.\n\n- Get a unique subdomain and unlimited email addresses for free.\n- Easily automate E2E password reset and account verification by catching emails.\n- Receive SMS messages and automate SMS tests.\n- Virtual SMTP and SMS support to test without 3rd party clients.\n\n## Get started\n\nFor a more step-by-step walkthrough see the [Cypress Guide](https://docs.mailisk.com/guides/cypress.html).\n\n### Requirements\n\n- Node.js 20 or newer\n\n### Installation\n\n#### Install with npm\n\n```shell\nnpm install --save-dev cypress-mailisk\n```\n\n#### Install with Yarn\n\n```shell\nyarn add cypress-mailisk --dev\n```\n\n#### Add to Cypress\n\nAfter installing the package add the following in your project's `cypress/support/e2e.js`:\n\n```js\nimport 'cypress-mailisk';\n```\n\n## Setup API Key\n\nTo be able to use the API you will need to add your [API key](http://docs.mailisk.com/#getting-your-api-key) to `cypress.config.js`:\n\n```js\nmodule.exports = defineConfig({\n  env: {\n    MAILISK_API_KEY: 'YOUR_API_KEY',\n  },\n});\n```\n\n## Usage\n\nThe cypress-mailisk plugin provides additional commands which can be accessed on the cypress object, for example `cy.mailiskSearchInbox()`. These commands extend the Chainable object which allows you to use the [`then()`](https://docs.cypress.io/api/commands/then#Usage) method to chain commands.\n\n### cy.mailiskSearchInbox\n\nThis is the main command to interact with Mailisk, it wraps the [Search Inbox](/api-reference/search-inbox) endpoint. See the reference documentation for the full list of filters and their description.\n\n```js\ncy.mailiskSearchInbox('yournamespace', { to_addr_prefix: 'test.user@', subject_includes: 'register' }).then(\n  (response) =\u003e {\n    const emails = response.data;\n    expect(emails).to.not.be.empty;\n  },\n);\n```\n\nThis command does a few extra things out of the box:\n\n- Waits until at least one new email arrives (override with `wait: false`).\n- Times out after 5 minutes if nothing shows up (adjust via `requestOptions.timeout`).\n- Ignores messages older than 15 minutes to avoid picking up leftovers from previous tests (change via `from_timestamp`).\n\n#### Quick examples\n\n```js\n// wait up to the default 5 min for *any* new mail\ncy.mailiskSearchInbox(namespace);\n// custom 60-second timeout\ncy.mailiskSearchInbox(namespace, {}, { timeout: 1000 * 60 });\n// polling pattern — return immediately, even if inbox is empty\ncy.mailiskSearchInbox(namespace, { wait: false });\n// returns the last 20 emails in the namespace immediately\ncy.mailiskSearchInbox(namespace, { wait: false, from_timestamp: 0, limit: 20 });\n```\n\n#### Filter by destination address\n\nA common pattern is to wait for the email your UI just triggered (e.g. password-reset).\nPass `to_addr_prefix` so you don’t pick up stale messages:\n\n```js\ncy.mailiskSearchInbox(namespace, {\n  to_addr_prefix: `test.user@${namespace}.mailisk.net`,\n}).then((response) =\u003e {\n  const emails = response.data;\n  expect(emails).to.not.be.empty;\n});\n```\n\n#### Filter by sender address\n\nUse `from_addr_includes` to narrow results to a sender or domain. This is useful when multiple systems write to the same namespace but only one sender matters for the test.\n\n```js\ncy.mailiskSearchInbox(namespace, {\n  from_addr_includes: '@example.com',\n}).then((response) =\u003e {\n  const emails = response.data;\n  expect(emails).to.not.be.empty;\n});\n```\n\n#### Filter by subject contents\n\nThe `subject_includes` filter helps when the UI sends different notification types from the same sender. Matching is case-insensitive and only requires the provided string to be present.\n\n```js\ncy.mailiskSearchInbox(namespace, {\n  to_addr_prefix: `test.user@${namespace}.mailisk.net`,\n  subject_includes: 'password reset',\n}).then((response) =\u003e {\n  const emails = response.data;\n  expect(emails).to.not.be.empty;\n});\n```\n\n### cy.mailiskGetAttachment\n\nThis command retrieves attachment metadata including download URL, filename, content type, and size.\n\n```js\ncy.mailiskGetAttachment('attachment-id').then((attachment) =\u003e {\n  console.log(attachment.data.filename);\n  console.log(attachment.data.content_type);\n  console.log(attachment.data.size);\n});\n```\n\n### cy.mailiskDownloadAttachment\n\nThis command downloads the actual attachment content as a Buffer. It first retrieves the attachment metadata, then downloads the file from the provided download URL.\n\n```js\ncy.mailiskDownloadAttachment('attachment-id').then((buffer) =\u003e {\n  cy.writeFile('downloads/attachment.pdf', buffer);\n});\n```\n\n### cy.mailiskSearchSms\n\nThis is the main command to interact with Mailisk SMS, it wraps the [Search SMS](/api-reference/search-sms) endpoint. Use a phone number that is registered to your account.\n\n```js\ncy.mailiskSearchSms('phoneNumber', { from_date: new Date('2023-01-01T00:00:00Z'), limit: 5 }).then((response) =\u003e {\n  const smsMessages = response.data;\n});\n```\n\nThis Cypress command does a few extra things out of the box compared to calling the raw API directly:\n\n- Waits until at least one SMS matches the filters (override with `wait: false`).\n- Times out after 5 minutes if nothing shows up (adjust via `requestOptions.timeout`).\n- Ignores SMS older than 15 minutes by default (override with `from_date`).\n\n#### Quick examples\n\n```js\n// wait up to the default 5 min for *any* new SMS sent to the phone number\ncy.mailiskSearchSms('phoneNumber');\n// custom 60-second timeout\ncy.mailiskSearchSms('phoneNumber', {}, { timeout: 1000 * 60 });\n// polling pattern — return immediately, even if inbox is empty\ncy.mailiskSearchSms('phoneNumber', { wait: false });\n// returns the last 20 SMS messages for the phone number immediately\ncy.mailiskSearchSms('phoneNumber', { wait: false, from_date: new Date(0), limit: 20 });\n```\n\n#### Filter by sender phone number\n\nUse `from_number` to narrow results to a specific phone number.\n\n```js\ncy.mailiskSearchSms('phoneNumber', {\n  from_number: '1234567890',\n}).then((response) =\u003e {\n  const smsMessages = response.data;\n});\n```\n\n#### Filter by body contents\n\nUse `body` to narrow results to a specific message body.\n\n```js\ncy.mailiskSearchSms('phoneNumber', {\n  body: 'Here is your code:',\n}).then((response) =\u003e {\n  const smsMessages = response.data;\n});\n```\n\n### cy.mailiskListSmsNumbers\n\nThis command lists the SMS numbers available to the current API key.\n\n```js\ncy.mailiskListSmsNumbers().then((response) =\u003e {\n  const smsNumbers = response.data;\n  expect(smsNumbers).to.not.be.empty;\n});\n```\n\n## Common test cases\n\n### Working with email attachments\n\nThis example demonstrates how to search for emails with attachments and download them:\n\n```js\ndescribe('Test email attachments', () =\u003e {\n  const namespace = 'yournamespace';\n  const testEmailAddr = `test.user@${namespace}.mailisk.net`;\n\n  it('Finds email with attachment and downloads it', () =\u003e {\n    cy.mailiskSearchInbox(namespace, {\n      to_addr_prefix: testEmailAddr,\n      subject_includes: 'invoice',\n    }).then((response) =\u003e {\n      expect(response.data).to.not.be.empty;\n      const email = response.data[0];\n\n      // Check if email has attachments\n      expect(email.attachments).to.not.be.empty;\n      const attachment = email.attachments[0];\n\n      // Get attachment metadata\n      cy.mailiskGetAttachment(attachment.id).then((attachmentData) =\u003e {\n        expect(attachmentData.data.filename).to.contain('.pdf');\n        expect(attachmentData.data.content_type).to.equal('application/pdf');\n\n        // Download the attachment\n        cy.mailiskDownloadAttachment(attachment.id).then((buffer) =\u003e {\n          // Save to downloads folder\n          cy.writeFile(`downloads/${attachmentData.data.filename}`, buffer);\n\n          // Verify file was downloaded\n          cy.readFile(`downloads/${attachmentData.data.filename}`).should('exist');\n        });\n      });\n    });\n  });\n});\n```\n\n### Password reset page\n\nThis example demonstrates going to a password reset page, requesting a new password, receiving reset code link via email and finally setting the new password.\n\n```js\ndescribe('Test password reset', () =\u003e {\n  let resetLink;\n  const namespace = 'yournamespace';\n  const testEmailAddr = `test.test@${namespace}.mailisk.net`;\n\n  it('Starts a password reset', () =\u003e {\n    cy.visit('https://example.com/password_reset');\n    cy.get('#email_field').type(testEmailAddr);\n  });\n\n  it('Gets a password reset email', () =\u003e {\n    cy.mailiskSearchInbox(namespace, {\n      to_addr_prefix: testEmailAddr,\n      subject_includes: 'password',\n    }).then((response) =\u003e {\n      expect(response.data).to.not.be.empty;\n      const email = response.data[0];\n      expect(email.subject).to.equal('Please reset your password');\n      resetLink = email.text.match(/.(https:\\/\\/example.com\\/password_reset\\/.*)\u003e\\n*/)[1];\n      expect(resetLink).to.not.be.undefined;\n    });\n  });\n\n  it('Goes to password reset link', () =\u003e {\n    cy.visit(resetLink);\n    cy.title().should('contain', 'Change your password');\n    cy.get('#password').type('MyNewPassword');\n    cy.get('#password_confirmation').type('MyNewPassword');\n    cy.get('form').submit();\n  });\n});\n```\n\nSee the full [Mailisk Documentation](https://docs.mailisk.com) for more examples and information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmailisk-app%2Fcypress-mailisk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmailisk-app%2Fcypress-mailisk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmailisk-app%2Fcypress-mailisk/lists"}