From 25b221d1d3ddf318b305b7eccc97419d96fc97db Mon Sep 17 00:00:00 2001 From: Mike Penz Date: Sun, 3 Mar 2024 08:32:56 +0000 Subject: [PATCH] - improve documentation to test the action in GitHub codespaces - simplify README - include demo test case to speed up setup --- README.md | 72 ++++++++++++------------------------- __tests__/demo/demo.test.ts | 47 ++++++++++++++++++++++++ package.json | 1 + 3 files changed, 71 insertions(+), 49 deletions(-) create mode 100644 __tests__/demo/demo.test.ts diff --git a/README.md b/README.md index d6ae196..f261a6d 100644 --- a/README.md +++ b/README.md @@ -722,7 +722,7 @@ export GITHUB_TOKEN=your_personal_github_pat ## Local Testing 🧪 -This GitHub action is fully developed in Typescript and can be run locally via npm or right from the browser using GitHub Codespace. +This GitHub action is fully developed in Typescript and can be run locally via `npm` or right from the browser using `GitHub Codespace`. [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/mikepenz/release-changelog-builder-action) @@ -730,67 +730,41 @@ Doing so is a great way to test the action and/or your custom configurations loc To run locally, or to access private repositories (GitHub Codespaces has automatic access to public repos with the default token), you will require to provide a valid `GITHUB_TOKEN` with read only permissions to access the repositories you want to run this action towards. (See more details in [Token Permission](#Token-Permission)) +To test your own configuration and usecase, the project contains a [__tests__/demo/demo.test.ts](https://github.com/mikepenz/release-changelog-builder-action/blob/develop/__tests__/demo/demo.test.ts) file, modify this one to your needs. (e.g. change repo, change token, change settings, ...), and then run it via: + +```bash +npm test -- demo.test.ts +``` + +
Debugging with Breakpoints +

+ +One major benefit of setting up a custom test is that it will allow you to use javascripts full debugging support, including the option of breakpoints via (for example) Visual Code. + +From GitHub codespaces, open the terminal panel -> Click the small arrow down beside `+` and pick `JavaScript Debug Terminal` (make sure to export the token again). Now execute the test with this terminal. (This is very similar to local Visual Code environments). + +

+
+ +
Run common tests +

+ +To run the common tests of the action, you require to export a valid github token. + ``` # Export the token in the CLI you use to execute. export GITHUB_TOKEN=your_read_only_github_token ``` -Afterwards it is possible to run the tests included in the project: +Afterwards it is possible to run any test included in the project: ```bash npm test -- main.test.ts # modify the file name to run other testcases ``` -To test your own configuration, it's adviced to create a new `__tests__/custom.test.ts` file, modify it to your needs (e.g. change repo, change token, change settings, ...), and then run it via `npm test -- custom.test.ts` - -

custom.test.ts -

- -```typescript -import {mergeConfiguration, resolveConfiguration} from '../src/utils' -import {ReleaseNotesBuilder} from '../src/releaseNotesBuilder' - -jest.setTimeout(180000) - -it('Test custom changelog builder', async () => { - const configuration = mergeConfiguration(undefined, resolveConfiguration( - '', - 'configs_test/configuration_approvers.json' - )) - const releaseNotesBuilder = new ReleaseNotesBuilder( - null, // baseUrl - null, // token - '.', // repoPath - 'mikepenz', // user - 'release-changelog-builder-action-playground', // repo - '1.5.0', // fromTag - '2.0.0', // toTag - false, // includeOpen - false, // failOnError - false, // ignorePrePrelease - false, // enable to fetch via commits - false, // enable to fetch reviewers - false, // enable to fetch release information - false, // enable to fetch reviews - 'PR', // set the mode to use [PR, COMMIT, HYBRID] - false, // enable exportCache - false, // enable exportOnly - null, // path to the cache - configuration // configuration - ) - - const changeLog = await releaseNotesBuilder.build() - console.log(changeLog) -}) -``` -

-One major benefit of setting up a custom test is that it will allow you to use javascripts full debugging support, including the option of breakpoints via (for example) Visual Code. - -From GitHub codespaces, open the terminal panel -> Click the small arrow down beside `+` and pick `JavaScript Debug Terminal` (make sure to export the token again). Now execute the test with this terminal. (This is very similar to local Visual Code environments). - ## Token Permission Permissions depend on the specific usecase, however this action only requires `read-only` permissions as it will not make modifications to the repository. diff --git a/__tests__/demo/demo.test.ts b/__tests__/demo/demo.test.ts new file mode 100644 index 0000000..cceb766 --- /dev/null +++ b/__tests__/demo/demo.test.ts @@ -0,0 +1,47 @@ +import {mergeConfiguration, resolveConfiguration} from '../../src/utils' +import {ReleaseNotesBuilder} from '../../src/releaseNotesBuilder' +import { GithubRepository } from '../../src/repositories/GithubRepository' + +jest.setTimeout(180000) + +// Define the token to use. Either retrieved from the environment. +// Alternatively provide it as a string right here. +const token = process.env.GITHUB_TOKEN || '' +const githubRepository = new GithubRepository(token, undefined, '.') +it('Test custom changelog builder', async () => { + // define the configuration file to use. + // By default it retireves a configuration from a json file + // You can also quickly modify in code. + const configuration = mergeConfiguration(undefined, resolveConfiguration( + '', + 'configs/configuration.json' + )) + + // Demo to modify the configuration further in code + // configuration.pr_template = "#{{TITLE}}" + + const releaseNotesBuilder = new ReleaseNotesBuilder( + null, // The base url used for the API requests (not needed for normal github) + githubRepository, // Repository implementation (allows tu test gitea). Keep default for GitHub + '.', // Root path to the checked out sources. Commonly keep as default + 'mikepenz', // The owner of the repo to test + 'release-changelog-builder-action-playground', // The repository name + '1.5.0', // `fromTag` The from tag name or the SHA1 of the from commit + '2.0.0', // `toTag` The to tag name or the SHA1 of the to commit + false, // `includeOpen` Define if you want to include open PRs into the changelog + false, // `failOnError` Define if the action should fail on errors + false, // `ignorePrePrelease` used if no `fromTag` is defined to resolve the prior tag + false, // `fetchViaCommits` enable to fetch via commits + false, // `fetchReviewers` Enables fetching of reviewers for building the changlog (does additional API requests) + false, // `fetchReleaseInformation` Enable to fetch release information (does additional API requests) + false, // `fetchReviews` Enable to fetch reviews of the PRs (does additional API requests) + 'PR', // `mode` Set the mode to use [PR, COMMIT, HYBRID]. PR -> builds changelog using PRs, COMMIT -> using commits, HYBRID -> Uses both + false, // `exportCache` Exports the fethced information to the cahce. Not relevant for this test + false, // `exportOnly` Enables to only export the fetched information however not build a changleog + null, // `cache` Path to the cache. Not relevant for this test. + configuration // The configuration to use for building the changelog + ) + + const changeLog = await releaseNotesBuilder.build() + console.log(changeLog) +}) \ No newline at end of file diff --git a/package.json b/package.json index 7d5cf14..783abc2 100644 --- a/package.json +++ b/package.json @@ -14,6 +14,7 @@ "test": "jest", "test-github": "jest __tests__/*.test.ts", "test-gitea": "jest __tests__/gitea/*.test.ts", + "test-demo": "jest __tests__/demo/*.test.ts", "all": "npm run build && npm run format && npm run lint && npm run package && npm run test-github" }, "repository": {