Skip to content

Latest commit

 

History

History
192 lines (135 loc) · 5.37 KB

development.md

File metadata and controls

192 lines (135 loc) · 5.37 KB
title description
Development
Learn how to develop and contribute to the Lando Mailpit service

Development

Development of this plugin happens on GitHub.

Requirements

At the very least you will need to have the following installed:

Getting Started

  1. Clone the repository:

    git clone https://github.com/lando/mailpit.git
cd mailpit

  2. Install dependencies:

    npm install

  3. Set up your development environment:

    • Ensure you have Node.js 20 or later installed
    • If you're using VS Code, consider installing the ESLint extension for real-time linting feedback

Working with the Plugin

This plugin contains various working and tested Lando apps in the examples/ folder. You should use these or create new ones to help with plugin development.

Each example contains the following section in its Landofile:

plugins:
  "@lando/mailpit": ../..

This tells Lando that this app should use the source version of the @lando/mailpit plugin you cloned down in the installation. This is useful because it allows you to isolate development within this repo without interfering with any other apps using the stable and global version of the plugin.

You should almost always develop against apps in the examples folder and those apps should always contain the above plugins config. If you have an existing Lando application you want to develop against, you can temporarily tell it to use the cloned down version of the plugin with:

plugins:
  "@lando/mailpit": /path/to/plugin

Repository Structure

This repository is structured as follows:

  • builders/: Contains the main service builder for the Mailpit plugin
  • config/: Contains configuration files used in services managed by the Mailpit plugin
  • docs/: Documentation for the Mailpit plugin
  • examples/: Example configurations and usage scenarios executed by Leia for testing
  • scripts/: Contains scripts used by the Mailpit plugin inside apps
  • tasks/: Contains Lando command implementations
  • test/: Contains unit test files
  • utils/: Utility functions used by the Mailpit plugin

Documentation

If you want to help with contributing documentation, you can use these commands:

# launch local docs site
npm run docs:dev

# build docs locally
npm run docs:build

# preview built docs locally
npm run docs:build

The documentation uses VitePress with our custom theme.

Testing

This project uses both unit tests and integration tests:

# Run unit tests
npm run test:unit

# Run integration tests
npm run test:leia

# Run all tests
npm test

Integration Tests with Leia

We use Leia for end-to-end testing. Leia is our custom testing framework that allows us to define tests as a series of shell commands in markdown files, making our tests both executable and human-readable documentation.

Each example in the examples/ directory serves as a test case. The README.md in each example contains the test steps in this format:

Start up tests
--------------

# Should start up successfully
lando start

Verification commands
---------------------

# Should be able to send mail
lando php /app/mail.php

# Should be able to see mail in the UI
lando exec mailpit -- curl localhost:8025/api/v1/messages

Destroy tests
-------------

# Should be able to destroy our app
lando destroy -y

The headers in these files are important:

  • Start up tests: Commands that run before the main tests
  • Verification commands: The main test steps (required)
  • Destroy tests: Clean up commands to run after tests

To run the tests:

# Run all integration tests
npm run test:leia

# Run a specific test
npx leia examples/basic/README.md -c 'Destroy tests'

Adding New Tests

When adding new test examples:

  1. Create a new directory in examples/
  2. Add a README.md with your test steps
  3. Add the test to GitHub Actions by modifying the workflow file:
jobs:
  leia-tests:
    strategy:
      fail-fast: false
      matrix:
        leia-test:
          - examples/basic
          - examples/advanced
          # Add your new test here

Linting

This project uses ESLint for code linting. The configuration is defined in eslint.config.js using the new flat config format:

npm run lint

Releasing

To deploy and publish a new version:

  1. Create a release on GitHub
  2. Use semantic versioning for the release title (e.g. v1.1.2)
  3. The GitHub release will automatically prepare and deploy to NPM

Note:

  • Creating a "pre-release" will tag the NPM package with edge instead of latest
  • To install specific versions: 
    # Latest stable release
npm install @lando/mailpit
# Latest pre-release
npm install @lando/mailpit@edge

Contributing

We welcome contributions! Please follow GitHub flow for contributions.