From b8d72515b6ecf712c92bed41d3687db81aca6eff Mon Sep 17 00:00:00 2001 From: Gasan <465806+gusega@users.noreply.github.com> Date: Wed, 22 Jan 2025 12:02:55 +0100 Subject: [PATCH 01/10] Update 02-build-system.md documentation how to run jest tests in intellij Signed-off-by: Gasan <465806+gusega@users.noreply.github.com> --- docs/tooling/cli/02-build-system.md | 33 +++++++++++++++++++++++------ 1 file changed, 27 insertions(+), 6 deletions(-) diff --git a/docs/tooling/cli/02-build-system.md b/docs/tooling/cli/02-build-system.md index 8f9b086c33..f2a6974b86 100644 --- a/docs/tooling/cli/02-build-system.md +++ b/docs/tooling/cli/02-build-system.md @@ -598,14 +598,35 @@ For your productivity working with unit tests it's quite essential to have your #### IntelliJ IDEA -1. Update Jest configuration template by: +At the moment it's not possible to run jest tests via jest command line. That is, if you run the following command from the project root: +```bash +NODE_OPTIONS='--no-node-snapshot --experimental-vm-modules' node node_modules/jest-cli/bin/jest.js --config packages/cli/config/jest.js +``` -- Click on "Edit Configurations" on top panel -- In the modal dialog click on link "Edit configuration templates..." located in the bottom left corner. -- In "Jest package" you have to point to relative path of jest module (it will be suggested by IntelliJ), i.e. `~/proj/backstage/node_modules/jest` -- In "Jest config" point to your jest configuration file, use absolute path for that, i.e. `--config /Users/user/proj/backstage/packages/cli/config/jest.js --runInBand` +You will get an error `Unexpected token 'export'` complaining about one of the imports from the `jest.js` config file. But why does jest work then when running `backstage-cli repo test`? +The reason is that `packages/cli/bin/backstage-cli` first executes `require('@backstage/cli/config/nodeTransform.cjs');` that probably transforms config files so that jest can use them. +Even simply adding `require('@backstage/cli/config/nodeTransform.cjs');` to the beginning of `node_modules/jest/bin/jest.js`, will make jest command line above work. -2. Now you can run any tests by clicking on green arrow located on `describe` or `it`. +Happily, there is a better way to do it, because `backstage-cli repo test` is simply a starter of the `jest-cli` with extra parameters. That is, you can run jest from the command line via `backstage-cli repo test` like this: +```bash +NODE_OPTIONS='--no-node-snapshot --experimental-vm-modules' node node_modules/@backstage/cli/bin/backstage-cli repo test +``` + +`backstage-cli` adds `--passWithNoTests --watch --workerIdleMemoryLimit=1000M --config node_modules/@backstage/cli/config/jest.js` jest options. + +So, to run it in intellij do the following: + +1. Update Jest configuration template by: + 1. Click on "Edit Configurations" on top panel + 2. In the modal dialog click on link "Edit configuration templates..." located in the bottom left corner. + 3. "Configuration file": leave empty (`backstage-cli` adds the config) + 4. "Node options": `--no-node-snapshot --experimental-vm-modules` + 5. "Jest package": `~/workspace/backstage/node_modules/@backstage/cli` - the location of the backstage cli package. + 6. "Working directory": `~/workspace/backstage` + 7. "Jest Options": `repo test --runInBand` + 8. "Environment variables": `backstage-cli` adds `--watch` jest option, so if you want your tests to stop after you run them, add `CI=true` + +2. Another issue is that if you right click on the test, intellij will create a playwright configuration, see [WEB-67720](https://youtrack.jetbrains.com/issue/WEB-67720/Jest-test-runs-as-playwright-test). So, to run jest tests create a configuration manually, the intellij will pick up the configuration template, provide there the test file. After intellij run tests in the file you can click on the individual tests in the run panel and re-run them, intellij will create a correct jest run configuration. #### VS Code From f929fb1f1a8e6c50c25ab30305edabcd482c434f Mon Sep 17 00:00:00 2001 From: Gasan <465806+gusega@users.noreply.github.com> Date: Wed, 22 Jan 2025 12:43:37 +0100 Subject: [PATCH 02/10] Update 02-build-system.md 1. replace intellij with Intellij 2. update config file location Signed-off-by: Gasan <465806+gusega@users.noreply.github.com> --- docs/tooling/cli/02-build-system.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/tooling/cli/02-build-system.md b/docs/tooling/cli/02-build-system.md index f2a6974b86..38a76eacd4 100644 --- a/docs/tooling/cli/02-build-system.md +++ b/docs/tooling/cli/02-build-system.md @@ -600,10 +600,10 @@ For your productivity working with unit tests it's quite essential to have your At the moment it's not possible to run jest tests via jest command line. That is, if you run the following command from the project root: ```bash -NODE_OPTIONS='--no-node-snapshot --experimental-vm-modules' node node_modules/jest-cli/bin/jest.js --config packages/cli/config/jest.js +NODE_OPTIONS='--no-node-snapshot --experimental-vm-modules' node node_modules/jest-cli/bin/jest.js --config node_modules/@backstage/cli/config/jest.js ``` -You will get an error `Unexpected token 'export'` complaining about one of the imports from the `jest.js` config file. But why does jest work then when running `backstage-cli repo test`? +You will get an error `SyntaxError: Unexpected token 'export'` complaining about one of the imports from the `jest.js` config file. But why does jest work then when running `backstage-cli repo test`? The reason is that `packages/cli/bin/backstage-cli` first executes `require('@backstage/cli/config/nodeTransform.cjs');` that probably transforms config files so that jest can use them. Even simply adding `require('@backstage/cli/config/nodeTransform.cjs');` to the beginning of `node_modules/jest/bin/jest.js`, will make jest command line above work. @@ -614,7 +614,7 @@ NODE_OPTIONS='--no-node-snapshot --experimental-vm-modules' node node_modules/@b `backstage-cli` adds `--passWithNoTests --watch --workerIdleMemoryLimit=1000M --config node_modules/@backstage/cli/config/jest.js` jest options. -So, to run it in intellij do the following: +So, to run it in Intellij do the following: 1. Update Jest configuration template by: 1. Click on "Edit Configurations" on top panel @@ -626,7 +626,7 @@ So, to run it in intellij do the following: 7. "Jest Options": `repo test --runInBand` 8. "Environment variables": `backstage-cli` adds `--watch` jest option, so if you want your tests to stop after you run them, add `CI=true` -2. Another issue is that if you right click on the test, intellij will create a playwright configuration, see [WEB-67720](https://youtrack.jetbrains.com/issue/WEB-67720/Jest-test-runs-as-playwright-test). So, to run jest tests create a configuration manually, the intellij will pick up the configuration template, provide there the test file. After intellij run tests in the file you can click on the individual tests in the run panel and re-run them, intellij will create a correct jest run configuration. +2. Another issue is that if you right click on the test, Intellij will create a playwright configuration, see [WEB-67720](https://youtrack.jetbrains.com/issue/WEB-67720/Jest-test-runs-as-playwright-test). So, to run jest tests create a configuration manually, the Intellij will pick up the configuration template, provide there the test file. After Intellij run tests in the file you can click on the individual tests in the run panel and re-run them, Intellij will create a correct jest run configuration. #### VS Code From 58c950d76bd7c3b8cec7fd779cbcb69b3315cc8c Mon Sep 17 00:00:00 2001 From: Gasan <465806+gusega@users.noreply.github.com> Date: Wed, 22 Jan 2025 17:10:08 +0100 Subject: [PATCH 03/10] Update accept.txt added Intellij to vocabulary Signed-off-by: Gasan <465806+gusega@users.noreply.github.com> --- .github/vale/config/vocabularies/Backstage/accept.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/vale/config/vocabularies/Backstage/accept.txt b/.github/vale/config/vocabularies/Backstage/accept.txt index 34ea8cc894..007dd8b70f 100644 --- a/.github/vale/config/vocabularies/Backstage/accept.txt +++ b/.github/vale/config/vocabularies/Backstage/accept.txt @@ -513,3 +513,5 @@ zoomable zsh scrollable severities +Intellij +intellij From bfeec270b216393059c573d39859963f0e9f87d6 Mon Sep 17 00:00:00 2001 From: Gasan <465806+gusega@users.noreply.github.com> Date: Fri, 24 Jan 2025 14:07:35 +0100 Subject: [PATCH 04/10] Update accept.txt add intellij variant Signed-off-by: Gasan <465806+gusega@users.noreply.github.com> --- .github/vale/config/vocabularies/Backstage/accept.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/vale/config/vocabularies/Backstage/accept.txt b/.github/vale/config/vocabularies/Backstage/accept.txt index 007dd8b70f..752fb04fa3 100644 --- a/.github/vale/config/vocabularies/Backstage/accept.txt +++ b/.github/vale/config/vocabularies/Backstage/accept.txt @@ -515,3 +515,4 @@ scrollable severities Intellij intellij +IntelliJ From 75defba1e8a2b725efd582e9a3bc58ea71907be6 Mon Sep 17 00:00:00 2001 From: Gasan <465806+gusega@users.noreply.github.com> Date: Fri, 24 Jan 2025 14:27:11 +0100 Subject: [PATCH 05/10] Update 02-build-system.md Signed-off-by: Gasan <465806+gusega@users.noreply.github.com> --- docs/tooling/cli/02-build-system.md | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/docs/tooling/cli/02-build-system.md b/docs/tooling/cli/02-build-system.md index 38a76eacd4..52853d353f 100644 --- a/docs/tooling/cli/02-build-system.md +++ b/docs/tooling/cli/02-build-system.md @@ -596,25 +596,34 @@ Caching is used sparingly throughout the Backstage build system. It is always us For your productivity working with unit tests it's quite essential to have your debugging configured in IDE. It will help you to identify the root cause of the issue faster. -#### IntelliJ IDEA +#### Preface At the moment it's not possible to run jest tests via jest command line. That is, if you run the following command from the project root: ```bash NODE_OPTIONS='--no-node-snapshot --experimental-vm-modules' node node_modules/jest-cli/bin/jest.js --config node_modules/@backstage/cli/config/jest.js ``` -You will get an error `SyntaxError: Unexpected token 'export'` complaining about one of the imports from the `jest.js` config file. But why does jest work then when running `backstage-cli repo test`? -The reason is that `packages/cli/bin/backstage-cli` first executes `require('@backstage/cli/config/nodeTransform.cjs');` that probably transforms config files so that jest can use them. -Even simply adding `require('@backstage/cli/config/nodeTransform.cjs');` to the beginning of `node_modules/jest/bin/jest.js`, will make jest command line above work. +You will get an error `SyntaxError: Unexpected token 'export'` complaining about one of the imports from the `node_modules/@backstage/cli/config/jest.js` config file. +But why does jest work then when running `backstage-cli repo test`? +The reason is that `packages/cli/bin/backstage-cli` first executes `require('@backstage/cli/config/nodeTransform.cjs');` that probably transforms config files so that jest can digest them. +Even simply adding `require('@backstage/cli/config/nodeTransform.cjs');` to the beginning of `node_modules/jest/bin/jest.js`, will make jest work in the script above. Happily, there is a better way to do it, because `backstage-cli repo test` is simply a starter of the `jest-cli` with extra parameters. That is, you can run jest from the command line via `backstage-cli repo test` like this: ```bash +NODE_OPTIONS='--no-node-snapshot --experimental-vm-modules' node_modules/.bin/backstage-cli repo test +``` +or +```bash NODE_OPTIONS='--no-node-snapshot --experimental-vm-modules' node node_modules/@backstage/cli/bin/backstage-cli repo test ``` + `backstage-cli` adds `--passWithNoTests --watch --workerIdleMemoryLimit=1000M --config node_modules/@backstage/cli/config/jest.js` jest options. -So, to run it in Intellij do the following: +With that in mind, let's configure IDE's to run `backstage-cli` in the role of jest. + + +#### IntelliJ IDEA 1. Update Jest configuration template by: 1. Click on "Edit Configurations" on top panel @@ -623,16 +632,17 @@ So, to run it in Intellij do the following: 4. "Node options": `--no-node-snapshot --experimental-vm-modules` 5. "Jest package": `~/workspace/backstage/node_modules/@backstage/cli` - the location of the backstage cli package. 6. "Working directory": `~/workspace/backstage` - 7. "Jest Options": `repo test --runInBand` - 8. "Environment variables": `backstage-cli` adds `--watch` jest option, so if you want your tests to stop after you run them, add `CI=true` + 7. "Jest Options": `repo test --runInBand --watch=false` -2. Another issue is that if you right click on the test, Intellij will create a playwright configuration, see [WEB-67720](https://youtrack.jetbrains.com/issue/WEB-67720/Jest-test-runs-as-playwright-test). So, to run jest tests create a configuration manually, the Intellij will pick up the configuration template, provide there the test file. After Intellij run tests in the file you can click on the individual tests in the run panel and re-run them, Intellij will create a correct jest run configuration. +2. Currently intellij has an issue that if you right click on a jest test and press "run", intellij will create a playwright run configuration instead of jest configuration, see [WEB-67720](https://youtrack.jetbrains.com/issue/WEB-67720/Jest-test-runs-as-playwright-test). + + Until intellij maintainers resolved the issue, create a jest configuration manually. Happily, intellij will pre-fill the configuration from the template. The only thing you need to do is provide path to the test file. Note, that after intellij runs test in the file you can click on the individual tests from the run panel and re-run them, this time intellij will create a correct jest run configuration. #### VS Code ```jsonc { - "jest.jestCommandLine": "node_modules/.bin/jest --config node_modules/@backstage/cli/config/jest.js", + "jest.jestCommandLine": "node_modules/.bin/backstage-cli --config node_modules/@backstage/cli/config/jest.js", // In a large repo like the Backstage main repo you likely want to disable // watch mode and the initial test run too, leaving just manual and perhaps // on-save test runs in place. From 901b5046afc5e14ee4372244dea80edd7909a9ee Mon Sep 17 00:00:00 2001 From: Gasan Guseinov Date: Tue, 28 Jan 2025 13:08:13 +0100 Subject: [PATCH 06/10] case insensitive intellij spelling Signed-off-by: Gasan Guseinov --- .github/vale/config/vocabularies/Backstage/accept.txt | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/vale/config/vocabularies/Backstage/accept.txt b/.github/vale/config/vocabularies/Backstage/accept.txt index 752fb04fa3..8af842d7f5 100644 --- a/.github/vale/config/vocabularies/Backstage/accept.txt +++ b/.github/vale/config/vocabularies/Backstage/accept.txt @@ -513,6 +513,4 @@ zoomable zsh scrollable severities -Intellij intellij -IntelliJ From f6c927fa7c5bca6cacbf94e9390eb51924329f2b Mon Sep 17 00:00:00 2001 From: Gasan <465806+gusega@users.noreply.github.com> Date: Tue, 28 Jan 2025 13:09:52 +0100 Subject: [PATCH 07/10] Update docs/tooling/cli/02-build-system.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fredrik Adelöw Signed-off-by: Gasan <465806+gusega@users.noreply.github.com> --- docs/tooling/cli/02-build-system.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tooling/cli/02-build-system.md b/docs/tooling/cli/02-build-system.md index 52853d353f..048251d26d 100644 --- a/docs/tooling/cli/02-build-system.md +++ b/docs/tooling/cli/02-build-system.md @@ -620,7 +620,7 @@ NODE_OPTIONS='--no-node-snapshot --experimental-vm-modules' node node_modules/@b `backstage-cli` adds `--passWithNoTests --watch --workerIdleMemoryLimit=1000M --config node_modules/@backstage/cli/config/jest.js` jest options. -With that in mind, let's configure IDE's to run `backstage-cli` in the role of jest. +With that in mind, let's configure IDEs to run `backstage-cli` in the role of jest. #### IntelliJ IDEA From 87f2f3862c3dc1856a88e83c17623176c6593fb4 Mon Sep 17 00:00:00 2001 From: Gasan Guseinov Date: Tue, 28 Jan 2025 13:35:50 +0100 Subject: [PATCH 08/10] update doc Signed-off-by: Gasan Guseinov --- docs/tooling/cli/02-build-system.md | 32 ++++++----------------------- 1 file changed, 6 insertions(+), 26 deletions(-) diff --git a/docs/tooling/cli/02-build-system.md b/docs/tooling/cli/02-build-system.md index 048251d26d..0843dec2a5 100644 --- a/docs/tooling/cli/02-build-system.md +++ b/docs/tooling/cli/02-build-system.md @@ -596,36 +596,16 @@ Caching is used sparingly throughout the Backstage build system. It is always us For your productivity working with unit tests it's quite essential to have your debugging configured in IDE. It will help you to identify the root cause of the issue faster. -#### Preface - -At the moment it's not possible to run jest tests via jest command line. That is, if you run the following command from the project root: -```bash -NODE_OPTIONS='--no-node-snapshot --experimental-vm-modules' node node_modules/jest-cli/bin/jest.js --config node_modules/@backstage/cli/config/jest.js -``` - -You will get an error `SyntaxError: Unexpected token 'export'` complaining about one of the imports from the `node_modules/@backstage/cli/config/jest.js` config file. -But why does jest work then when running `backstage-cli repo test`? -The reason is that `packages/cli/bin/backstage-cli` first executes `require('@backstage/cli/config/nodeTransform.cjs');` that probably transforms config files so that jest can digest them. -Even simply adding `require('@backstage/cli/config/nodeTransform.cjs');` to the beginning of `node_modules/jest/bin/jest.js`, will make jest work in the script above. - -Happily, there is a better way to do it, because `backstage-cli repo test` is simply a starter of the `jest-cli` with extra parameters. That is, you can run jest from the command line via `backstage-cli repo test` like this: -```bash -NODE_OPTIONS='--no-node-snapshot --experimental-vm-modules' node_modules/.bin/backstage-cli repo test -``` -or -```bash -NODE_OPTIONS='--no-node-snapshot --experimental-vm-modules' node node_modules/@backstage/cli/bin/backstage-cli repo test -``` - - -`backstage-cli` adds `--passWithNoTests --watch --workerIdleMemoryLimit=1000M --config node_modules/@backstage/cli/config/jest.js` jest options. - -With that in mind, let's configure IDEs to run `backstage-cli` in the role of jest. +We cannot execute tests with just raw `jest`, because there are a few concerns such as module transforms that need to be in place for the `jest` runtime to be happy. +Therefore, we delegate to the Backstage CLI to wrap the jest run for us, since it knows how to put those things in place. +This aligns things so that your in-IDE test runs work the same way as your CI and manual command line test runs do. +With that in mind, here are some IDEs configurations to run backstage components' `jest` tests with `backstage-cli` in the role of `jest`. #### IntelliJ IDEA 1. Update Jest configuration template by: + 1. Click on "Edit Configurations" on top panel 2. In the modal dialog click on link "Edit configuration templates..." located in the bottom left corner. 3. "Configuration file": leave empty (`backstage-cli` adds the config) @@ -634,7 +614,7 @@ With that in mind, let's configure IDEs to run `backstage-cli` in the role of je 6. "Working directory": `~/workspace/backstage` 7. "Jest Options": `repo test --runInBand --watch=false` -2. Currently intellij has an issue that if you right click on a jest test and press "run", intellij will create a playwright run configuration instead of jest configuration, see [WEB-67720](https://youtrack.jetbrains.com/issue/WEB-67720/Jest-test-runs-as-playwright-test). +2. Currently, intellij has an issue that if you right-click on a jest test and press "run", intellij will create a playwright run configuration instead of jest configuration, see [WEB-67720](https://youtrack.jetbrains.com/issue/WEB-67720/Jest-test-runs-as-playwright-test). Until intellij maintainers resolved the issue, create a jest configuration manually. Happily, intellij will pre-fill the configuration from the template. The only thing you need to do is provide path to the test file. Note, that after intellij runs test in the file you can click on the individual tests from the run panel and re-run them, this time intellij will create a correct jest run configuration. From 7e610194656be44921fc32135dbeaf15c9ea88ea Mon Sep 17 00:00:00 2001 From: Gasan <465806+gusega@users.noreply.github.com> Date: Tue, 28 Jan 2025 16:15:46 +0100 Subject: [PATCH 09/10] Update docs/tooling/cli/02-build-system.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fredrik Adelöw Signed-off-by: Gasan <465806+gusega@users.noreply.github.com> --- docs/tooling/cli/02-build-system.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tooling/cli/02-build-system.md b/docs/tooling/cli/02-build-system.md index 0843dec2a5..e34eb85b0a 100644 --- a/docs/tooling/cli/02-build-system.md +++ b/docs/tooling/cli/02-build-system.md @@ -622,7 +622,7 @@ With that in mind, here are some IDEs configurations to run backstage components ```jsonc { - "jest.jestCommandLine": "node_modules/.bin/backstage-cli --config node_modules/@backstage/cli/config/jest.js", + "jest.jestCommandLine": "yarn test", // In a large repo like the Backstage main repo you likely want to disable // watch mode and the initial test run too, leaving just manual and perhaps // on-save test runs in place. From 182120afd53b8cddb19f3f29d94d7f435d5ae72e Mon Sep 17 00:00:00 2001 From: Gasan <465806+gusega@users.noreply.github.com> Date: Tue, 28 Jan 2025 16:16:05 +0100 Subject: [PATCH 10/10] Update docs/tooling/cli/02-build-system.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fredrik Adelöw Signed-off-by: Gasan <465806+gusega@users.noreply.github.com> --- docs/tooling/cli/02-build-system.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tooling/cli/02-build-system.md b/docs/tooling/cli/02-build-system.md index e34eb85b0a..6a03df9607 100644 --- a/docs/tooling/cli/02-build-system.md +++ b/docs/tooling/cli/02-build-system.md @@ -616,7 +616,7 @@ With that in mind, here are some IDEs configurations to run backstage components 2. Currently, intellij has an issue that if you right-click on a jest test and press "run", intellij will create a playwright run configuration instead of jest configuration, see [WEB-67720](https://youtrack.jetbrains.com/issue/WEB-67720/Jest-test-runs-as-playwright-test). - Until intellij maintainers resolved the issue, create a jest configuration manually. Happily, intellij will pre-fill the configuration from the template. The only thing you need to do is provide path to the test file. Note, that after intellij runs test in the file you can click on the individual tests from the run panel and re-run them, this time intellij will create a correct jest run configuration. + Until intellij maintainers resolve the issue, create a jest configuration manually. Happily, intellij will pre-fill the configuration from the template. The only thing you need to do is provide a path to the test file. Note, that after intellij runs test in the file you can click on the individual tests from the run panel and re-run them, this time intellij will create a correct jest run configuration. #### VS Code