From 355650973f33cca652c57c341e30c0b248b54cb0 Mon Sep 17 00:00:00 2001 From: Krishnan Mahadevan Date: Sat, 14 Aug 2021 12:42:06 +0530 Subject: [PATCH] User documentation for TestNG contributors MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes #2597 Following was done: 1. Added the “idea” plugin 2. Created module specific build files for ease of working in a multi module project. 3. Added some basic user facing documentation into “CONTRIBUTING.md” --- .github/CONTRIBUTING.md | 50 +++++++++++++++++++ .github/ISSUE_TEMPLATE.md | 4 +- .gitignore | 2 + build.gradle.kts | 1 + settings.gradle.kts | 6 +++ ...gradle.kts => testng-ant-build.gradle.kts} | 0 ...gradle.kts => testng-api-build.gradle.kts} | 0 ...le.kts => testng-asserts-build.gradle.kts} | 0 ...gradle.kts => testng-bom-build.gradle.kts} | 0 ...ts => testng-collections-build.gradle.kts} | 0 ...e.kts => testng-core-api-build.gradle.kts} | 0 ...radle.kts => testng-core-build.gradle.kts} | 0 ... testng-reflection-utils-build.gradle.kts} | 0 ...kts => testng-runner-api-build.gradle.kts} | 0 ... => testng-runner-junit4-build.gradle.kts} | 0 ...e.kts => testng-test-kit-build.gradle.kts} | 0 ....kts => testng-test-osgi-build.gradle.kts} | 0 ...ild.gradle.kts => testng-build.gradle.kts} | 0 18 files changed, 61 insertions(+), 2 deletions(-) rename testng-ant/{build.gradle.kts => testng-ant-build.gradle.kts} (100%) rename testng-api/{build.gradle.kts => testng-api-build.gradle.kts} (100%) rename testng-asserts/{build.gradle.kts => testng-asserts-build.gradle.kts} (100%) rename testng-bom/{build.gradle.kts => testng-bom-build.gradle.kts} (100%) rename testng-collections/{build.gradle.kts => testng-collections-build.gradle.kts} (100%) rename testng-core-api/{build.gradle.kts => testng-core-api-build.gradle.kts} (100%) rename testng-core/{build.gradle.kts => testng-core-build.gradle.kts} (100%) rename testng-reflection-utils/{build.gradle.kts => testng-reflection-utils-build.gradle.kts} (100%) rename testng-runner-api/{build.gradle.kts => testng-runner-api-build.gradle.kts} (100%) rename testng-runner-junit4/{build.gradle.kts => testng-runner-junit4-build.gradle.kts} (100%) rename testng-test-kit/{build.gradle.kts => testng-test-kit-build.gradle.kts} (100%) rename testng-test-osgi/{build.gradle.kts => testng-test-osgi-build.gradle.kts} (100%) rename testng/{build.gradle.kts => testng-build.gradle.kts} (100%) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 98b3acdfdd..b8019d6eb3 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,5 +1,6 @@ # Need help? Before opening a new issue, did you ask your question on + * [Google group](https://groups.google.com/group/testng-users) * [StackOverflow](https://stackoverflow.com/questions/tagged/testng) @@ -9,6 +10,7 @@ If you posted on both sites, please provide the link to the other question to av Before posting the issue, try to reproduce the issue in [a shell window](https://testng.org/doc/documentation-main.html#running-testng). If the problem does not exist with the shell, first check if the issue exists on the bugtracker of the runner, and open an issue there first: + * Eclipse: https://github.com/cbeust/testng-eclipse/issues * IntelliJ: [https://youtrack.jetbrains.com/issues](https://youtrack.jetbrains.com/issues?q=%23%7BUnit%20Testing.%20TestNG%7D%20) * Maven: https://issues.apache.org/jira/browse/SUREFIRE @@ -18,6 +20,7 @@ If the problem does not exist with the shell, first check if the issue exists on Always make sure your issue is happening on the latest TestNG version. Bug reports occurring on older versions will not be looked at quickly. # Have you considered sending a pull request instead of filing an issue? + The best way to report a bug is to provide the TestNG team with a full test case reproducing the issue. Maybe you can write a runnable test case (check the `src/test/` folder for examples) and propose it in a pull request Don't worry if the CI fails because it is the expected behavior. @@ -30,3 +33,50 @@ This pull request will be a perfect start to find the fix :) If your pull request involves fixing SonarQube issues then we would suggest that you please discuss this with the [TestNG-dev](https://groups.google.com/forum/#!forum/testng-dev) before you spend time working on it. + +# Working with the codebase + +### List all tasks + +After cloning the project, run `./gradlew tasks` to list out all the tasks that are available. + +### Importing into IntelliJ + +To import the TestNG project into IntelliJ run `./gradlew openIdea` + +### Running all tests + +To run all the test cases (build the code) run `./gradlew test` + +### Running tests that belong to a specific module + +* First list the sub-modules that are available in the TestNG codebase by running `./gradlew projects` +* Now you can run tests that belong to any specific module by running `./gradlew ::test`. For e.g., to run tests under the sub-module **testng-asserts** run the command : `./gradlew :testng-asserts:test` + +The codebase makes use of [autostyle](https://github.com/autostyle/autostyle) to enforce code formatting and also fixing code formatting. + +To check if there are any code formatting/styling issues (Its best to run this before every pull request), run `./gradlew autostyleCheck` + +To automatically fix any styling issues run `./gradlew autostyleApply` + +**Tip:** + +In order to automatically have the formatting applied as and when you commit code, you can do the following: + +1. Create a new file under `.git/hooks/pre-commit` +2. Now add the below contents to this file and save it. + +``` +# run the auto style applying on the code +./gradlew autostyleApply + +# store the last exit code in a variable +RESULT=$? + +# return the './gradlew autostyleApply' exit code +exit $RESULT +``` + +This will cause git to trigger the code styling automatically right before commiting your changes locally. + +After that you can quickly check if there were any formatting that was applied using `git status` diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index 9b949d45d6..a17615ff2f 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.github/ISSUE_TEMPLATE.md @@ -7,7 +7,7 @@ ### Actual behavior -### Is the issue reproductible on runner? +### Is the issue reproducible on runner? - [ ] Shell - [ ] Maven @@ -19,4 +19,4 @@ ### Test case sample -> Please, share the test case (as small as possible) which shows the issue \ No newline at end of file +> Please, share the test case (as small as possible) which shows the issue diff --git a/.gitignore b/.gitignore index c76fe52737..412e5342d2 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,8 @@ .classpath .gradle .idea +*.ipr +*.iws *.iml .project .settings diff --git a/build.gradle.kts b/build.gradle.kts index 1117699810..2c434139ae 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -1,6 +1,7 @@ plugins { id("testng.repositories") id("com.github.vlsi.stage-vote-release") + id("idea") } val String.v: String get() = rootProject.extra["$this.version"] as String diff --git a/settings.gradle.kts b/settings.gradle.kts index fd968bb14f..99b7be8269 100644 --- a/settings.gradle.kts +++ b/settings.gradle.kts @@ -33,3 +33,9 @@ include(":testng-test-osgi") enableFeaturePreview("VERSION_CATALOGS") enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS") + +for (project in rootProject.children) { + project.apply { + buildFileName = "${project.name}-build.gradle.kts" + } +} diff --git a/testng-ant/build.gradle.kts b/testng-ant/testng-ant-build.gradle.kts similarity index 100% rename from testng-ant/build.gradle.kts rename to testng-ant/testng-ant-build.gradle.kts diff --git a/testng-api/build.gradle.kts b/testng-api/testng-api-build.gradle.kts similarity index 100% rename from testng-api/build.gradle.kts rename to testng-api/testng-api-build.gradle.kts diff --git a/testng-asserts/build.gradle.kts b/testng-asserts/testng-asserts-build.gradle.kts similarity index 100% rename from testng-asserts/build.gradle.kts rename to testng-asserts/testng-asserts-build.gradle.kts diff --git a/testng-bom/build.gradle.kts b/testng-bom/testng-bom-build.gradle.kts similarity index 100% rename from testng-bom/build.gradle.kts rename to testng-bom/testng-bom-build.gradle.kts diff --git a/testng-collections/build.gradle.kts b/testng-collections/testng-collections-build.gradle.kts similarity index 100% rename from testng-collections/build.gradle.kts rename to testng-collections/testng-collections-build.gradle.kts diff --git a/testng-core-api/build.gradle.kts b/testng-core-api/testng-core-api-build.gradle.kts similarity index 100% rename from testng-core-api/build.gradle.kts rename to testng-core-api/testng-core-api-build.gradle.kts diff --git a/testng-core/build.gradle.kts b/testng-core/testng-core-build.gradle.kts similarity index 100% rename from testng-core/build.gradle.kts rename to testng-core/testng-core-build.gradle.kts diff --git a/testng-reflection-utils/build.gradle.kts b/testng-reflection-utils/testng-reflection-utils-build.gradle.kts similarity index 100% rename from testng-reflection-utils/build.gradle.kts rename to testng-reflection-utils/testng-reflection-utils-build.gradle.kts diff --git a/testng-runner-api/build.gradle.kts b/testng-runner-api/testng-runner-api-build.gradle.kts similarity index 100% rename from testng-runner-api/build.gradle.kts rename to testng-runner-api/testng-runner-api-build.gradle.kts diff --git a/testng-runner-junit4/build.gradle.kts b/testng-runner-junit4/testng-runner-junit4-build.gradle.kts similarity index 100% rename from testng-runner-junit4/build.gradle.kts rename to testng-runner-junit4/testng-runner-junit4-build.gradle.kts diff --git a/testng-test-kit/build.gradle.kts b/testng-test-kit/testng-test-kit-build.gradle.kts similarity index 100% rename from testng-test-kit/build.gradle.kts rename to testng-test-kit/testng-test-kit-build.gradle.kts diff --git a/testng-test-osgi/build.gradle.kts b/testng-test-osgi/testng-test-osgi-build.gradle.kts similarity index 100% rename from testng-test-osgi/build.gradle.kts rename to testng-test-osgi/testng-test-osgi-build.gradle.kts diff --git a/testng/build.gradle.kts b/testng/testng-build.gradle.kts similarity index 100% rename from testng/build.gradle.kts rename to testng/testng-build.gradle.kts