Skip to content

Latest commit

 

History

History
204 lines (138 loc) · 10.2 KB

CONTRIBUTING.md

File metadata and controls

204 lines (138 loc) · 10.2 KB
Raw

Contributing to ably-js

Contributing

  1. Fork it
  2. When pulling to local, make sure to also pull the ably-common repo (git submodule init && git submodule update)
  3. Create your feature branch (git checkout -b my-new-feature)
  4. Commit your changes (git commit -am 'Add some feature')
  5. Ensure you have added suitable tests and the test suite is passing(npm test)
  6. Ensure the type definitions have been updated if the public API has changed
  7. Push the branch (git push origin my-new-feature)
  8. Create a new Pull Request

Release Process

  1. Make sure the tests are passing in CI for the branch you're building
  2. Create a new branch for the release, for example release/1.2.3
  3. Update the CHANGELOG.md with any customer-affecting changes since the last release and add this to the git index
  4. Run npm version <VERSION_NUMBER> --no-git-tag-version with the new version and add the changes to the git index
  5. Update the version number to the new version in src/platform/react-hooks/src/AblyReactHooks.ts
  6. Create a PR for the release branch
  7. Once the release PR is landed to the main branch, checkout the main branch locally (remember to pull the remote changes) and run npm run build
  8. Run git tag <VERSION_NUMBER> with the new version and push the tag to GitHub with git push <REMOTE> <VERSION_NUMBER> (usually git push origin <VERSION_NUMBER>)
  9. Run npm publish . (should require OTP) - publishes to NPM
  10. Run the GitHub action "Publish to CDN" with the new tag name
  11. Visit https://github.com/ably/ably-js/tags and create a GitHub release based on the new tag (for release notes, you generally can just copy the notes you added to the CHANGELOG)
  12. Update the Ably Changelog (via headwayapp) with these changes (again, you can just copy the notes you added to the CHANGELOG)

Building the library

To build the library, simply run npm run build. Building the library currently requires NodeJS >= v16.

Since webpack builds are slow, commands are also available to only build the output for specific platforms (eg npm run build:node), see package.json for the full list of available commands

Test suite

To run the Mocha tests, simply run the following command:

npm test

Mocha Tests

Run the Mocha test suite

npm run test:node

You can pass any Mocha CLI arguments and flags to the test:node script after the -- separator, for example running one test file:

npm run test:node -- test/realtime/auth.test.js

Or run just one test

npm run test:node -- --grep=test_name_here

Or run test skipping the build

npm run test:node:skip-build -- test/rest/status.test.js --grep=test_name_here

Tests alignment with the Ably features specification

Each test has a docstring explaining its relation to the Ably features specification. This is achieved by using the following tags in the docstring:

  • @spec - The test case directly tests all the functionality documented in the spec item.
  • @specpartial - The test case partially tests the functionality documented in the spec item. This can be due to the spec item having conditional statements, the spec item being too overloaded and covering points that could be split into multiple spec items, or the spec item being documented for the parent class but the test case tests the functionality for one of its descendant classes.
  • @nospec - No corresponding spec item was found for the test.
  • @specskip - (only when using it.skip) The test case is skipped during CI, so spec items related to this test case should not be taken into account when deciding on metrics for the spec coverage/feature tracking.

The @nospec and @specskip tags do not have any parameters. The @spec and @specpartial tags must provide a spec item ID from the Ably features specification (such as CSV2) and may include an optional comment after the hyphen explaining the test's behavior in relation to the mentioned spec item.

Here is how those tags are used in the codebase:

/**
 * @spec RSE2a
 * @spec RSE2b - optional comment clarifying how the spec is tested
 */
it('test 1', function (done) { ... });

/**
 * @specpartial RTC8a1
 * @specpartial RTC8a2 - optional comment clarifying how the spec is tested
 */
it('test 2', function (done) { ... });

/**
 * @spec RTN4a
 * @specpartial RTN4b - optional comment clarifying how the spec is tested
 */
it('test 3', function (done) { ... });

/**
 * @nospec
 */
it('test 4', function (done) { ... });

/**
 * @spec RTN9a
 * @specpartial RTN9b
 * @specskip
 */
it.skip('test 5', function (done) { ... });

Additionally, docstrings may include references to other related spec items. These spec items are not tested directly by the test case but may provide additional context for the test.

Adding new tests

When adding new tests to the suite, make sure to mark them with the corresponding docstring tags explaining the test's relation to the Ably features specification items. See the usable tags in Tests alignment with the Ably features specification.

Debugging the mocha tests locally with a debugger

Run the following command to launch tests with the debugger enabled. The tests will block until you attach a debugger.

node --inspect-brk=9229 node_modules/.bin/mocha

Alternatively you can also run the tests for single file

node --inspect-brk=9229 node_modules/.bin/mocha test/realtime/auth.test.js

The included vscode launch config allows you to launch and attach the debugger in one step, simply open the test file you want to run and start debugging. Note that breakpoint setting for realtime code will be within the browser/static directory, not the raw source files, and breakpoints in files under test should work directly.

Debugging the tests in a browser with Mocha test runner

Run the following command to start a local Mocha test runner web server

npm run test:webserver

Open your browser to http://localhost:3000. If you are using a remote browser, refer to https://docs.saucelabs.com/reference/sauce-connect/ for instructions on setting up a local tunnel to your Mocha runner web server.

Formatting/linting files

Run the following command to fix linting/formatting issues

npm run format

Testing environment variables for Node.js

All tests are run against the sandbox environment by default. However, the following environment variables can be set before running the Karma server to change the environment the tests are run against.

  • ABLY_ENV - defaults to sandbox, however this can be set to another known environment such as 'staging'
  • ABLY_REALTIME_HOST - explicitly tell the client library to use an alternate host for real-time websocket communication.
  • ABLY_REST_HOST - explicitly tell the client library to use an alternate host for REST communication.
  • ABLY_PORT - non-TLS port to use for the tests, defaults to 80
  • ABLY_TLS_PORT - TLS port to use for the tests, defaults to 443
  • ABLY_USE_TLS - true or false to enable/disable use of TLS respectively
  • ABLY_LOG_LEVEL - Log level for the client libraries, defaults to 2, 4 is MICRO

Testing environment variables for browser tests

When using the test webserver npm run test:webserver the following test variables can be configured by appending them as params in the URL such as http://localhost:3000/mocha.html?log_level=4.

  • env - defaults to sandbox, however this can be set to another known environment such as 'staging'
  • realtime_host - explicitly tell the client library to use an alternate host for real-time websocket communication.
  • host - explicitly tell the client library to use an alternate host for REST communication.
  • port - non-TLS port to use for the tests, defaults to 80
  • tls_port - TLS port to use for the tests, defaults to 443
  • tls - true or false to enable/disable use of TLS respectively
  • log_level - Log level for the client libraries, defaults to 2, 4 is MICRO

Adding private API annotations to tests

We have an ongoing project which aims to reuse the ably-js test suite as a unified test suite for all of our client libraries. To enable this work, we want to be able to monitor the test suite’s usage of APIs that are private to ably-js.

When you use a private API in a test, record its usage using the recordPrivateApi method on the test’s helper object. For example:

/* Sabotage the reattach attempt, then simulate a server-sent detach */
helper.recordPrivateApi('replace.channel.sendMessage');
channel.sendMessage = function () {};

The current list of private API usage identifiers can be found in test/common/modules/private_api_recorder.js; add new ones there as necessary.

The following test files do not utilise private API annotations, and you don’t need to add them:

React hooks

The react sample application is configured to execute using Vite - which will load a sample web app that acts as a simple test harness for the hooks.

You can run the dev server from the terminal using:

npm run start:react

You'll need to provide an API key for the sample to work (or you'll just get a white page and some errors in the console). To do this, create the file ./src/platform/react-hooks/sample-app/.env and add the following line:

VITE_ABLY_API_KEY=<your-api-key>

This API key will be loaded by the vite dev server at build time.

You can run the unit tests by running npm run test:react in the terminal.