release-node-project

September 13, 2023 ยท View on GitHub

Scripts for releasing Node.js-based projects

Prerequisites

  • NodeJS

  • Yarn

  • VSCode

    • To enable Editor SDK, run

      yarn dlx @yarnpkg/sdks vscode

      Then in TypeScript file, simultaneously press

      ctrl + shift + p

      and choose option

      Select TypeScript Version

      then select value

      Use Workspace Version

  • Docker

Install Dependencies

To install dependencies, run

yarn install

Start

To run code from non-built source code, run

yarn start

Build

To build the source code into transpiled javascript, run

yarn build

Watch

To automatically rebuild on file changes, run

yarn watch

Clean

To remove any previously built code, run

yarn clean

Run

To run transpiled javascript bundles, run:

yarn run-built

or directly with

node executable.js

Or through the bin command with

release-node-project

Lint

to check code for programmatic or stylistic problems, run

yarn lint

To automatically fix lint problems, run

yarn lint-fix

Test

To test the project for regressions, run

npm test

This will lint the project, then run unit and e2e tests.

Test execution can be configured with the following environment variables:

NameRequiredDefaultDescriptionExample(s)
TEST_RESULT_NAMENoIf specified, will record test results to the given file name and collect coverage.unit

Unit Tests

Unit tests are for stateless logic tests on small, contained parts of the code base (ideally not reliant on/mock anything outside their scope), and can be run with

yarn test-unit

Note: To run a specific test, execute

yarn test-unit -t 'test name'

With spaces separating describe blocks and test names

End to End Tests

End to End (E2E) Tests run against the final, distributable executable and are meant to test overarching scenarios of the tool to simulate as close as possible the real interactions and use/edge cases.

E2E tests can be run with

yarn test:e2e

Note: To run a specific test, execute

yarn test-e2e -t 'test name'

With spaces separating describe blocks and test names.

The E2E tests reach out to the public GitHub instance. Best practices are to avoid reliance on external/third-party interactions for testing, so Wiremock (as a dynamically created docker container) is used to simulate a GitHub instance.

First, Wiremock must "record" responses from GitHub by acting as a proxy:

yarn test-e2e-record

Then, recordings can be "played back" to run E2E tests without needing to reach out to GitHub:

yarn test-e2e-playback

When run in CI, the test-e2e-playback is used to avoid brittleness by reliance on the actual GitHub public server.

Code Coverage

Code coverage can be generated by running

yarn test-unit-ci

There is no code coverage for e2e tests as those do not run against source code, but transpiled binaries.

To view code coverage in the browser, run

yarn coverage-view

Upgrade Yarn

To upgrade the version of yarn used in the project, run

yarn set version latest

then install to have the change picked up.