Contributing to Mockjax

April 14, 2026 ยท View on GitHub

First of all, thank you for helping make Mockjax the best it can be! We truly appreciate the support. Before you submit that Pull Request, please be sure to follow these guidelines.

Key Points

Commits

Smaller commits

Keep commits small and atomic. That means one significant change per commit if possible. For if you are submitting a PR that fixes a bug, updates a piece of documentation, and cleans up some whitespace, please place all three of those things in separate commits! This allows us to roll back specific work (if needed) without destroying the entire contribution. Larger changes that depend on one another may be the exception, but look for opportunities for this.

Commit messages

Your commit messages should clearly identify why the changes were made. We can see the diff to know what was changed. Keep them short and sweet, identifying the purpose of the change and allowing commits to be scanned easily.

Try to keep the code style consistent

As much as possible we need to try to keep the coding style consistent within the codebase. That means using the same indentation style, quotes, spacing, etc. You can run our style checker using:

npm run style:check

If you want eslint to automatically correct style issues you can run:

npm run style

Additionally, you should lint the code looking for things like dead lines, potential bugs, or out dated code elements. You can do this automatically with:

npm run lint

Write tests

We really need to see tests for any commit other than documentation. If you are fixing a bug, add a breaking test first, then the code that fixes that test. If you are developing a new feature, add complete tests for the feature. That includes tests for success cases as well as failure cases!

We use QUnit as our testing tool of choice, so please write them using that API. You should probably add both a unit test (found in /test/unit) and an integration test (found in /test/integration). Try to match the style of the existing test suite! Add your test(s) to the appropriate module.

Mocks

For the unit tests, we have mocks of jQuery and the few other global objects that Mockjax relies on. Take a look at how they are used in the unit tests. For the integration tests, we generally do not use mocks.

Run the tests

There are four test suites: unit, integration, nodejs, and requirejs. They each use slightly different setup, but generally they report results the same way. You can run each of them from the terminal, but you can also run the integration tests in a browser (and you should run them in multiple browsers).

npm run test       # alias for test:unit
npm run test:unit  # run only the unit tests (no headless browser)

npm run test:integration         # alias for test:integration:latest
npm run test:integration:all     # run the integration test suite in a headless chrome browser against all supported versions of jQuery
npm run test:integration:latest  # run the integration test suite in a headless chrome browser against the latest supported version of jQuery

npm run test:nodejs     # run the Node.js (CommonJS) test suite
npm run test:requirejs  # run the RequireJS test suite

npm run test:all  # alias for running test:unit, test:integration:all, test:nodejs, and test:requirejs

Run tests in real browsers

You should be able to run a small local static HTTP server:

cd /path/to/mockjax
npx http-server -c-1 -p 3000

And then just visit http://localhost:3000/test/integration in your browser. Once there, be sure to click through each of the jQuery versions in the header to run the tests against each version.

Run your tests everywhere

Lastly, we'd like you to run your tests on as many browsers as possible. Check the main README file for the browsers we support.

We highly recommend running your tests in a virtual environment to capture any issues in specific browsers. You can do so easily with our BrowserStack integration. You can run the integration test suite using the command below. All you need to do is set the BROWSERSTACK_USERNAME and BROWSERSTACK_KEY environment variables first.

export BROWSERSTACK_USERNAME="your-username"
export BROWSERSTACK_KEY="your-key"
npm run test:browserstack

Submit Your PR

This is the last step! First, be sure you're merging with the correct branch! Version 3.x of Mockjax is on the master branch, but if you're submitting a bug fix for v2.x, make sure it is submitted to the correct branch (as well as master, if the bug exists in both).

Be sure to identify everything that is within your pull request in the description. If you have code that fixes a bug and also cleans up some documentation, please specify both! Additionally, if your PR fixes or resolves a specific GitHub issue please reference it using the #[id] format so that the two can be linked!

For new features, be sure to include information on how to use the feature in the main README. And for bugs, information on how to reproduce the bug is helpful!

Publish a release

Although individual contributors cannot publish a release, it's good to have documentation on what goes into that in case anyone needs to take over the process. Currently, @jakerella is the only one doing so.

  1. Create a new branch for your version (maybe named vx.y.z)
  2. Run style checks, linting, and all tests:
    • Using npm run build:dist captures all of this
    • Also run node browserstack.js for cross-browser / OS checks
  3. Update the CHANGELOG.md, package.json version, and any other necessary files.
    • The version for Mockjax is ONLY located in the package.json
  4. Make sure to generate fresh /dist files and commit those.
    • Running npm run build:dist in step 1 covered this, or run npm run build
  5. Submit your PR for the new version branch.
  6. Ask others for input on the PR.
  7. If all is well, merge the branch into master.
  8. Create a release on Github with a tag matching the version number and changelog info.
  9. Run npm publish on master to push the new version up to npm.
    • Be sure you're logged into npm!