-
Notifications
You must be signed in to change notification settings - Fork 9
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
76aada0
commit b22532d
Showing
1 changed file
with
50 additions
and
68 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,12 +1,10 @@ | ||
| Ladybug debug- and test tool by WeAreFrank! | ||
| =========================================== | ||
| # Ladybug debug- and test tool by WeAreFrank! | ||
|
|
||
| Ladybug, developed and maintained by the integration company WeAreFrank!, adds message based debugging and message based | ||
| unit testing, system testing and regression testing to your Java application. Call Ladybug at certain checkpoints in | ||
| your code (either directly or using AOP) to generate tree based reports. Implement a rerun method to be able to rerun | ||
| reports and optionally stub certain checkpoints for regression testing. | ||
|
|
||
|
|
||
| # Contents | ||
|
|
||
| - [Releases](#releases) | ||
|
|
@@ -25,22 +23,17 @@ reports and optionally stub certain checkpoints for regression testing. | |
| - [Create and publish NPM package and WebJar](#create-and-publish-npm-package-and-webjar) | ||
| - [CI/CD](#cicd) | ||
|
|
||
| Releases | ||
| ======== | ||
| # Releases | ||
|
|
||
| See [release notes](RELEASES.md). | ||
|
|
||
|
|
||
| Feedback | ||
| ======== | ||
| # Feedback | ||
|
|
||
| For bug reports and feature requests create a new issue at <https://github.com/ibissource/ibis-ladybug/issues>. Ladybug | ||
| is developed and maintained by [WeAreFrank!](https://wearefrank.nl/). Contact us at <https://wearefrank.nl/en/contact/> | ||
| or send an email to [email protected]. | ||
|
|
||
|
|
||
| Ladybug online demo | ||
| =================== | ||
| # Ladybug online demo | ||
|
|
||
| To see Ladybug in action as part of the Frank!Framework go to: | ||
|
|
||
|
|
@@ -50,9 +43,7 @@ And in Open ZaakBrug as part of http://demodam.nl: | |
|
|
||
| - https://open-zaakbrug.demodam.nl/debug | ||
|
|
||
|
|
||
| How to use Ladybug | ||
| ================== | ||
| # How to use Ladybug | ||
|
|
||
| Ladybug is incorporated into the Frank!Framework and as such documented as part of the Frank!Manual. For a quick | ||
| introduction to Ladybug, read: | ||
|
|
@@ -63,9 +54,7 @@ For a detailed explanation please read (which will also explain the use of Ladyb | |
|
|
||
| - https://frank-manual.readthedocs.io/en/latest/testing/ladybug/ladybug.html | ||
|
|
||
|
|
||
| How to incorporate Ladybug into your application or framework | ||
| ============================================================= | ||
| # How to incorporate Ladybug into your application or framework | ||
|
|
||
| There are two main area's to consider, the actual logging/debugging of business logic and the configuration/integration | ||
| of Ladybug into your project. | ||
|
|
@@ -99,7 +88,7 @@ logger. | |
| ``` | ||
|
|
||
| The second area to consider while integrating Ladybug into your project is the Spring configuration and enabling of the | ||
| servlets needed to serve the Ladybug frontend. This can basically be done in two ways (direct and using | ||
| servlets needed to serve the Ladybug frontend. This can basically be done in two ways (direct and using | ||
| [AOP](https://docs.spring.io/spring-framework/docs/5.3.x/reference/html/core.html#spring-core)). We hope that the | ||
| following examples for both methods are enough to get you running. If not, don't hesitate to [contact us](#feedback) for | ||
| help. | ||
|
|
@@ -136,12 +125,9 @@ And the AOP related spring configuration xml: | |
|
|
||
| The [next section](#how-to-change-and-test-ladybug) also describes how to run Ladybug with the Frank!Framework. | ||
|
|
||
| # How to change and test Ladybug | ||
|
|
||
| How to change and test Ladybug | ||
| ============================== | ||
|
|
||
| General setup | ||
| ------------- | ||
| ## General setup | ||
|
|
||
| Clone the following projects to your Git folder or any other folder of your choice: | ||
|
|
||
|
|
@@ -153,8 +139,7 @@ Clone the following projects to your Git folder or any other folder of your choi | |
|
|
||
| Create skip-replace-inject.txt in the ibis-ladybug folder (see pom.xml for more info). | ||
|
|
||
| Backend development | ||
| ------------------- | ||
| ## Backend development | ||
|
|
||
| Read the Frank!Runner [README.md](https://github.com/ibissource/frank-runner#frankrunner) to learn how to integrate it | ||
| with your IDE but you can also just start the restart.bat in the frank-runner/specials/ibis-ladybug folder. This should | ||
|
|
@@ -170,38 +155,34 @@ properties as describes in the comments in this file. | |
| You can also enable spring.profiles.active=storage.file to use the file storage and see the reports generated by the | ||
| unit tests of the ibis-ladybug project in the Ladybug GUI. | ||
|
|
||
| Testing backend changes with Frank!Framework | ||
| -------------------------------------------- | ||
| ## Testing backend changes with Frank!Framework | ||
|
|
||
| To test your Ladybug changes with the Frank!Framework enable test.with.iaf=true. By default it will test with the webapp | ||
| module of the Frank!Framework. This can be changed with the iaf.module property. The frank-runner/specials folder | ||
| contains a folder per module that can have it's own build.properties with custom properties (see the build.xml for | ||
| possible values). | ||
|
|
||
| Frontend development | ||
| -------------------- | ||
| ## Frontend development | ||
|
|
||
| Please do the following to set up your development environment for the front-end: | ||
| * Install [Node.js](https://nodejs.org/en/), choose version 16. You should get executables `npm` version 8.x and `node` version 16.x. Check these versions using `npm -v` and `node -v`. | ||
| * Change directory to your checkout of ladybug-frontend. | ||
| * The Node Package Manager (npm) includes another package manager, yarn. We use that one because it is more stable. Enable it by executing the command `corepack enable`. You should do this in a command prompt that runs with administrator permissions. | ||
| * Use `yarn -v` to check that you have yarn version 3.2.x. | ||
| * Run `yarn install --frozen-lockfile` to install your dependencies. The flag ensures that you get exactly the same dependencies as the other developers have. If you want to include a new dependency, update `package.json` and do `yarn install`. File `yarn.lock` will be updated, the list of all dependencies including dependencies of other dependencies. Check in `yarn.lock` to ensure that other developers will update to the same dependencies as you. In case you don't have a direct internet connection you might need to set HTTPS_PROXY, see https://docs.cypress.io/guides/references/proxy-configuration. | ||
| * Run `yarn prepare` to prepare Git hooks. If you do not do this, you will not be able to commit or push in the ladybug-frontend project. | ||
|
|
||
| Testing frontend changes with the test webapp | ||
| --------------------------------------------- | ||
| - Install [Node.js](https://nodejs.org/en/), choose version 16. You should get executables `npm` version 8.x and `node` version 16.x. Check these versions using `npm -v` and `node -v`. | ||
| - Change directory to your checkout of ladybug-frontend. | ||
| - The Node Package Manager (npm) includes another package manager, yarn. We use that one because it is more stable. Enable it by executing the command `corepack enable`. You should do this in a command prompt that runs with administrator permissions. | ||
| - Use `yarn -v` to check that you have yarn version 3.2.x. | ||
| - Run `yarn install --immutable` to install your dependencies. The flag ensures that you get exactly the same dependencies as the other developers have. If you want to include a new dependency, update `package.json` and do `yarn install`. File `yarn.lock` will be updated, the list of all dependencies including dependencies of other dependencies. Check in `yarn.lock` to ensure that other developers will update to the same dependencies as you. In case you don't have a direct internet connection you might need to set HTTPS_PROXY, see https://docs.cypress.io/guides/references/proxy-configuration. | ||
| - Run `yarn prepare` to prepare Git hooks. If you do not do this, you will not be able to commit or push in the ladybug-frontend project. | ||
|
|
||
| * Start the backend using `frank-runner/specials/ibis-ladybug` as explained at [Backend development](#backend-development). Wait until Tomcat is up and running. | ||
| * Execute command `ng serve` from within the `ladybug-frontend` checkout. This wil make Node.js serve the Ladybug frontend files and proxy the Ladybug backend api as the src folder contains a proxy.conf.json (this will circumvent CORS related problems as the frontend served by Node.js on port 4200 would call the api on port 80). It is now possible to use both the WebJars packaged Ladybug frontend and the Ladybug frontend served by Node.js. The page on the following url (also mentioned above) contains links to both frontends: `http://localhost`. | ||
| ## Testing frontend changes with the test webapp | ||
|
|
||
| Testing frontend changes with Frank!Framework | ||
| --------------------------------------------- | ||
| - Start the backend using `frank-runner/specials/ibis-ladybug` as explained at [Backend development](#backend-development). Wait until Tomcat is up and running. | ||
| - Execute command `ng serve` from within the `ladybug-frontend` checkout. This wil make Node.js serve the Ladybug frontend files and proxy the Ladybug backend api as the src folder contains a proxy.conf.json (this will circumvent CORS related problems as the frontend served by Node.js on port 4200 would call the api on port 80). It is now possible to use both the WebJars packaged Ladybug frontend and the Ladybug frontend served by Node.js. The page on the following url (also mentioned above) contains links to both frontends: `http://localhost`. | ||
|
|
||
| ## Testing frontend changes with Frank!Framework | ||
|
|
||
| The Frank!Framework incorporates Ladybug and configures is a bit different then the test webapp. It for example adds a Gray box view which you might want to test. The Frank!Framework serves the Ladybug on a different url then the test webapp so you need to configure the previously mentioned proxy a bit different and change the url in src/proxy.conf.json from http://localhost/ladybug to http://localhost/iaf/ladybug. In case you also have backend changes you can start the Frank!Framework as eplained above (with test.with.iaf=true). Otherwise it is easier to for example run Frank2Example1. See the Frank!Runner [README.md](https://github.com/ibissource/frank-runner#frankrunner) for more information on how to start a Frank2Example1 or another Frank. | ||
|
|
||
| Testing frontend changes with unit tests | ||
| ---------------------------------------- | ||
| ## Testing frontend changes with unit tests | ||
|
|
||
| To run the unit tests of the frontend, run the following command: | ||
|
|
||
|
|
@@ -211,41 +192,41 @@ ng test | |
|
|
||
| At the time of writing, there are no unit tests but there are end-to-end tests. | ||
|
|
||
| End-to-end testing is done using [Cypress](https://www.cypress.io/). Cypress is a dependency configured in `package.json`, so it should have been installed when you did `yarn install --frozen-lockfile`. You have the following options for running the tests: | ||
| * `yarn run e2e`. This runs the end-to-end tests headless and without user interaction. | ||
| * `yarn run e2e-interactive`. This opens a Window from which you can choose what tests to start. You can select the webbrowser you want to test with. | ||
| End-to-end testing is done using [Cypress](https://www.cypress.io/). Cypress is a dependency configured in `package.json`, so it should have been installed when you did `yarn install --immutable`. You have the following options for running the tests: | ||
|
|
||
| - `yarn run e2e`. This runs the end-to-end tests headless and without user interaction. | ||
| - `yarn run e2e-interactive`. This opens a Window from which you can choose what tests to start. You can select the webbrowser you want to test with. | ||
|
|
||
| In case nothing happens after "Compiled successfully" you might need to run `set HTTP_PROXY=` to prevent Cypress from connecting to locahost using your | ||
| proxy. | ||
|
|
||
| When the tests are running, you will see the ibis-ladybug GUI. The GUI will show the effects of the commands that are applied by the tests. | ||
|
|
||
| Quarkus | ||
| ===== | ||
| # Quarkus | ||
|
|
||
| To see how to run the backend for Quarkus, please see [Quarkus backend](https://github.com/ibissource/ladybug-quarkus#demo-and-test-ladybug-in-quarkus).\ | ||
| For the frontend, do the following: | ||
| - Check out of the branch [Quarkus configuration](https://github.com/ibissource/ladybug-frontend/tree/quarkus-configuration) | ||
| - Run `ng serve --open` or run `ng serve` and navigate to [localhost/ladybug](http://localhost/ladybug/) | ||
| - NOTE: It is important to note that running a report in the test tab is not yet possible with Quarkus | ||
|
|
||
| Create and publish NPM package and WebJar | ||
| ======================================== | ||
| - Check out of the branch [Quarkus configuration](https://github.com/ibissource/ladybug-frontend/tree/quarkus-configuration) | ||
| - Run `ng serve --open` or run `ng serve` and navigate to [localhost/ladybug](http://localhost/ladybug/) | ||
| - NOTE: It is important to note that running a report in the test tab is not yet possible with Quarkus | ||
|
|
||
| # Create and publish NPM package and WebJar | ||
|
|
||
| ### Prerequisites | ||
|
|
||
| - Make sure the latest changes are committed (and preferably pushed) to the project | ||
| - Open your terminal and navigate to your project folder (so `PATH/TO/ladybug`) | ||
| - If this is the first time, you need to log into NPM | ||
| - Create an account on [NPM](https://www.npmjs.com/signup) if you don't have one yet. | ||
| - Ask a colleague to add your account to the WeAreFrank! organization. | ||
| - In the terminal run the following command `npm login`, which prompts you to log into NPM. | ||
| - Create an account on [NPM](https://www.npmjs.com/signup) if you don't have one yet. | ||
| - Ask a colleague to add your account to the WeAreFrank! organization. | ||
| - In the terminal run the following command `npm login`, which prompts you to log into NPM. | ||
|
|
||
| ### Creating and publishing an NPM package | ||
| - Run the command `yarn install --frozen-lockfile`, to sync with changes done by others | ||
|
|
||
| - Run the command `yarn install --immutable`, to sync with changes done by others | ||
| - Run the command `ng build`, to build the current project | ||
| - Copy the following files into the generated `dist/ladybug` folder | ||
| - README.md | ||
| - LICENSE | ||
| - package.json | ||
|
|
||
| - In the `dist/ladybug/index.html` change the types of the three scripts on line 15 to `application/javascript` (so `type="module"` -> `type="application/javascript"`). The specific scripts are: | ||
| - `runtime.e3a101410a4894ca.js` | ||
| - `polyfills.42dedf2fcdca615b.js` | ||
|
|
@@ -263,6 +244,7 @@ Create and publish NPM package and WebJar | |
| - You have now successfully published the NPM package, see https://www.npmjs.com/package/@wearefrank/ladybug | ||
|
|
||
| ### Creating and publishing WebJar | ||
|
|
||
| - Navigate to [WebJars](https://webjars.org) | ||
| - Click on the `Add a WebJar` button | ||
| - Select the type `NPM` | ||
|
|
@@ -272,11 +254,11 @@ Create and publish NPM package and WebJar | |
| - You have now published the WebJar, see (after a few hours) https://repo.maven.apache.org/maven2/org/webjars/npm/wearefrank__ladybug/ | ||
|
|
||
| ### Prepare for next cycle | ||
|
|
||
| - Go into the file `ladybug-frontend/package.json` and increment the version number (for example `0.0.12` -> `0.0.13`) | ||
| - Commit and push the changes in `ladybug-frontend/package.json`, with the commit message `Set version to X.Y.Z for the next development cycle` | ||
|
|
||
| CI/CD | ||
| ===== | ||
| # CI/CD | ||
|
|
||
| The preceeding sections explained how to change Ladybug. This section explains the CI/CD of Ladybug and it explains how we manage releases. | ||
|
|
||
|
|
@@ -286,10 +268,10 @@ WeAreFrank! has two automatic tests for Ladybug. First, our on-premise servers r | |
|
|
||
| The Cypress test is used in two ways. First, it can be triggered if ibis-ladybug is updated. Project ibis-ladybug has a GitHub action that triggers the Cypress test of the front-end. This can happen because the Cypress test can be triggered by a `workflow_dispatch` event, see [test script](.github/workflows/start-frontend-test.yml). In this scenario, the following four inputs are provided: | ||
|
|
||
| * frontendCommitToCheckout: ladybug-frontend commit to checkout, typically a reference to a tag. | ||
| * backendCommitToCheckout: ibis-ladybug commit to checkout, typically a branch name. | ||
| * useRealFrontend: `true`, because we do not want to use the checkout of ladybug-frontend, but the WebJar contained in ibis-ladybug. | ||
| * mergeMasterToBranch: `true`, for the backend directs the test to merge the master into the checkout. This way, a pull request of the backend is emulated. | ||
| - frontendCommitToCheckout: ladybug-frontend commit to checkout, typically a reference to a tag. | ||
| - backendCommitToCheckout: ibis-ladybug commit to checkout, typically a branch name. | ||
| - useRealFrontend: `true`, because we do not want to use the checkout of ladybug-frontend, but the WebJar contained in ibis-ladybug. | ||
| - mergeMasterToBranch: `true`, for the backend directs the test to merge the master into the checkout. This way, a pull request of the backend is emulated. | ||
|
|
||
| This scenario does not work on forks of the ibis-ladybug project. A fork does not have rights to trigger tests within the `ibissource/ladybug-frontend` project. A commit on `ibissource/ibis-ladybug` triggers the front-end test. GitHub will not show the success or failure of the front-end test. Please browse to https://github.com/ibissource/ladybug-frontend and go to "Actions". Check the latest test run there. | ||
|
|
||
|
|
@@ -311,4 +293,4 @@ When updating the front-end, work on a branch that is allowed to live on a fork | |
|
|
||
| Update the front-end and the backend simultaneously on your development PC. The front-end changes will fail in CI/CD because they are tested against the master of the backend. Rely on the Cypress test on your development PC and on the Maven build of ibis-ladybug to test your work. When you trust your work, release the front-end in a WebJar as explained in [Create and publish NPM package and WebJar](#create-and-publish-npm-package-and-webjar). Please note that the released commit may live on another branch than master. Ensure that the commit and the tag are pushed to GitHub project ibissource/ladybug-frontend. Then update `pom.xml` of ibis-ladybug to reference the new WebJar; do so on a branch pushed to ibissource/ibis-ladybug. This update of the backend triggers the GitHub actions front-end test as explained earlier. Check that the latest run of the front-end test succeeds. | ||
|
|
||
| At this point, you can merge your work on ibis-ladybug to its master branch. After this merge, additional pushes on your ladybug-frontend branch will succeed in CI/CD because the corresponding backend changes are in the backend master. You can merge your front-end changes to master if the GitHub actions test succeeds. | ||
| At this point, you can merge your work on ibis-ladybug to its master branch. After this merge, additional pushes on your ladybug-frontend branch will succeed in CI/CD because the corresponding backend changes are in the backend master. You can merge your front-end changes to master if the GitHub actions test succeeds. | ||