Skip to content

Latest commit

 

History

History
125 lines (107 loc) · 4.07 KB

Contribute.md

File metadata and controls

125 lines (107 loc) · 4.07 KB

Contributing

How to contribute

  • File issues.
  • Edit/write documentation.
  • Submit pull requests.
  • Test in different environments.
  • Raise awareness.

Summary of tools

Following tools are getting used:

Initial setup

Instructions on setting up development environment:

  • Install node and npm - https://nodejs.org/
  • Checkout code from GitHub - you may fork the code first into your GitHub account.
  • Use npm i to install dependencies:
    $ npm i
  • Install the Playwright browsers (only needed if you plan to run tests in a browser project):
    $ npx playwright install

Project structure

Important files and folders:

<Project Folder>
├── LICENSE
├── README.md
├── bin/                     -- Scripts invoked from `npm` tasks
├── bundles/                 -- Generated UMD bundle (build output)
├── esm6/                    -- Generated ES modules (build output)
├── eslint.config.mjs
├── package-lock.json
├── package.json
├── playwright.config.ts     -- Playwright projects: node, chromium, firefox, webkit
├── rabbitmq/
│   └── Dockerfile           -- This builds a docker image that is used to run test cases
├── rollup.config.mjs
├── spec/                    -- Test cases run via Playwright (Node and browser projects)
│   ├── helpers/
│   └── unit/                -- Unit tests
│       └── compatibility/   -- Tests for the compatibility (Stomp v5) API
├── src/                     -- Typescript sources
│   └── compatibility/       -- Code for compatibility mode
└── tsconfig.json

Setup a Stomp broker

  • A Stomp broker is used for running the tests. I have been using RabbitMQ.
  • The broker URL and credentials are defined in spec/helpers/connect-helpers.ts. Defaults assume RabbitMQ on localhost:15674.
  • Please note that in RabbitMQ you will need to enable Stomp and WebStomp plugins.
  • By default RabbitMQ WebStomp will treat messages as text, you will need to tell it to use binary frames:
    $ echo 'web_stomp.ws_frame = binary' >> /etc/rabbitmq/rabbitmq.conf
  • A RabbitMQ Dockerfile is provided with necessary plugins and configuration. To use it, run:
    $ docker build -t myrabbitmq rabbitmq/ # Needed only once
    $ docker run -d -p 15674:15674 myrabbitmq # to start the broker

Building and testing

Key npm tasks:

  • clean - Remove generated build artifacts
  • build - Build two variants - ES Modules and UMD
  • rollup - Internally used by npm run build
  • test - Run tests in Node via Playwright (--project=node)
  • test:coverage - Run tests under c8 and produce coverage reports (text, html, lcov)
  • lint - Run ESLint
  • prettier - Format source files with Prettier

Basic development workflow

  1. Checkout a new branch.
  2. Make code changes (src/specs)
  3. Build:
    $ npm run build
  4. Run tests:
    • Default (Node):
      $ npm run test
    • With coverage:
      $ npm run test:coverage
    • In a specific browser via Playwright:
      $ npx playwright test --project=chromium   # or firefox, webkit
    • Caution: All projects share the same broker and queue names, so running several projects against the same broker concurrently may cause unexpected failures.
  5. Lint and format before committing:
    $ npm run lint
    $ npm run prettier
  6. Update documentation - do update Change-log.md
  7. Please follow GitHub guidelines. Raise an issue if you are unclear.