[
{
"path": ".editorconfig",
"content": "root = true\n\n[*]\ncharset = utf-8\ntrim_trailing_whitespace = true\ninsert_final_newline = true\n\n[*.bat]\nend_of_line = crlf\n\n[*.md]\n# Trailing whitespace is important in Markdown (they distinguish a new line from a new paragraph)\ntrim_trailing_whitespace = false\n\n[*.{kt,kts}]\nij_kotlin_allow_trailing_comma = false\nij_kotlin_allow_trailing_comma_on_call_site = false\n\n[*.kts]\nindent_style = tab\n"
},
{
"path": ".gitattributes",
"content": "* text eol=lf\n*.bat text eol=crlf\n*.png binary\n*.key binary\n*.jar binary\n*.ttf binary\nrelease-notes-* merge=union\n"
},
{
"path": ".github/ISSUE_TEMPLATE/bug_report.md",
"content": "---\nname: Report a bug or regression\nabout: Create a report to help us improve\ntype: Bug\nlabels: [\"type: bug\"]\n---\n\n\n\n## Steps to reproduce\n\n\n\n## Context\n\n - Used versions (Jupiter/Vintage/Platform):\n - Build Tool/IDE:\n\n## Deliverables\n\n- [ ] ...\n"
},
{
"path": ".github/ISSUE_TEMPLATE/config.yml",
"content": "blank_issues_enabled: false\ncontact_links:\n - name: Ask a question\n url: https://github.com/junit-team/junit-framework/discussions/categories/q-a\n about: Please ask and answer questions here\n - name: Ask a question (Stack Overflow)\n url: https://stackoverflow.com/questions/tagged/junit5\n about: Alternatively, ask questions here\n"
},
{
"path": ".github/ISSUE_TEMPLATE/feature_request.md",
"content": "---\nname: Request a feature or enhancement\nabout: Suggest an idea for this project\ntype: Feature\nlabels: [\"type: new feature\"]\n---\n\n\n\n## Deliverables\n\n- [ ] ...\n"
},
{
"path": ".github/ISSUE_TEMPLATE/task.md",
"content": "---\nname: Create a task\nabout: Create a task for a specific piece of work\ntype: Task\nlabels: [\"type: task\"]\n---\n\n\n\n## Deliverables\n\n- [ ] ...\n"
},
{
"path": ".github/PULL_REQUEST_TEMPLATE.md",
"content": "\n\n---\n\nI hereby agree to the terms of the [JUnit Contributor License Agreement](https://github.com/junit-team/junit-framework/blob/002a0052926ddee57cf90580fa49bc37e5a72427/CONTRIBUTING.md#junit-contributor-license-agreement).\n\n---\n\n### Definition of Done\n\n- [ ] There are no TODOs left in the code\n- [ ] Method [preconditions](https://docs.junit.org/snapshot/api/org.junit.platform.commons/org/junit/platform/commons/util/Preconditions.html) are checked and documented in the method's Javadoc\n- [ ] [Coding conventions](https://github.com/junit-team/junit-framework/blob/HEAD/CONTRIBUTING.md#coding-conventions) (e.g. for logging) have been followed\n- [ ] Change is covered by [automated tests](https://github.com/junit-team/junit-framework/blob/HEAD/CONTRIBUTING.md#tests) including corner cases, errors, and exception handling\n- [ ] Public API has [Javadoc](https://github.com/junit-team/junit-framework/blob/HEAD/CONTRIBUTING.md#javadoc) and [`@API` annotations](https://apiguardian-team.github.io/apiguardian/docs/current/api/org/apiguardian/api/API.html)\n- [ ] Change is documented in the [User Guide](https://docs.junit.org/snapshot/) and [Release Notes](https://docs.junit.org/snapshot/release-notes.html)\n"
},
{
"path": ".github/actions/main-build/action.yml",
"content": "name: Main build\ndescription: Sets up JDKs and runs Gradle\ninputs:\n arguments:\n required: true\n description: Gradle arguments\n default: :platform-tooling-support-tests:test build eclipse --no-configuration-cache # Disable configuration cache due to https://github.com/diffplug/spotless/issues/2318\n encryptionKey:\n required: true\n description: Gradle cache encryption key\nruns:\n using: \"composite\"\n steps:\n - uses: ./.github/actions/setup-test-jdk\n - uses: ./.github/actions/run-gradle\n with:\n arguments: ${{ inputs.arguments }}\n encryptionKey: ${{ inputs.encryptionKey }}\n - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1\n if: ${{ always() }}\n with:\n name: Open Test Reports (${{ github.job }})\n path: '**/build/reports/open-test-report.html'\n"
},
{
"path": ".github/actions/maven-central-user-token/action.yml",
"content": "name: Prepare Maven Central user token\ndescription: Compute the Maven Central user token from username and password\ninputs:\n username:\n required: true\n description: Maven Central username\n password:\n required: true\n description: Maven Central password\nruns:\n using: \"composite\"\n steps:\n - shell: bash\n run: | # zizmor: ignore[github-env]\n USER_TOKEN=$(printf \"${USERNAME}:${PASSWORD}\" | base64)\n echo \"::add-mask::$USER_TOKEN\"\n echo \"MAVEN_CENTRAL_USER_TOKEN=$USER_TOKEN\" >> $GITHUB_ENV\n env:\n USERNAME: ${{ inputs.username }}\n PASSWORD: ${{ inputs.password }}\n"
},
{
"path": ".github/actions/run-gradle/action.yml",
"content": "name: Run Gradle\ndescription: Sets up Gradle JDKs and runs Gradle\ninputs:\n arguments:\n required: true\n description: Gradle arguments\n default: build\n broken-by-issue:\n required: false\n description: Expect the build to fail due the referenced GitHub issue\n default: \"\"\n encryptionKey:\n required: true\n description: Gradle cache encryption key\nruns:\n using: \"composite\"\n steps:\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0\n id: setup-gradle-jdk\n with:\n distribution: temurin\n java-version: 25\n check-latest: true\n - uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0\n with:\n cache-encryption-key: ${{ inputs.encryptionKey }}\n - uses: testlens-app/setup-testlens@d96a555133c275a00949d2cc77b70fe9a4242ebf # v1.9.2\n with:\n write-log-files: true\n - shell: bash\n env:\n JAVA_HOME: ${{ steps.setup-gradle-jdk.outputs.path }}\n run: | # zizmor: ignore[template-injection]\n ./gradlew \\\n -Dorg.gradle.java.installations.auto-download=false \\\n -Pjunit.develocity.buildCache.pushEnabled=${{ github.repository == 'junit-team/junit-framework' }} \\\n -Pjunit.develocity.predictiveTestSelection.enabled=true \\\n -Pjunit.develocity.predictiveTestSelection.selectRemainingTests=${{ github.event_name != 'pull_request' }} \\\n \"-Dscan.value.GitHub job=${{ github.job }}\" \\\n javaToolchains \\\n ${{ inputs.arguments }} || error_code=$?\n \n \n if [ -n \"${{ inputs.broken-by-issue }}\" ]; then\n if [ -n \"$error_code\" ]; then\n # we expected the build to fail, it failed => pass \n exit 0\n else \n # we expected the build to fail, it didn't => fail\n RED='\\033[0;31m'\n RESET='\\033[0m' # No Color\n echo \"${RED}Build was expected to fail, but it passed. Was ${{ inputs.broken-by-issue }} resolved?${RESET}\"\n exit 1 \n fi\n fi\n \n # exit with the original error code if set\n if [ -n \"$error_code\" ]; then\n exit \"$error_code\"\n fi\n - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1\n if: ${{ always() }}\n with:\n name: TestLens logs (${{ github.job }} - ${{ job.check_run_id }})\n path: '**/build/**/testlens-logs/**'\n if-no-files-found: ignore\n"
},
{
"path": ".github/actions/setup-test-jdk/action.yml",
"content": "name: Set up Test JDK\ndescription: Sets up the JDK required to run platform-tooling-support-tests\ninputs:\n distribution:\n required: true\n description: 'The JDK distribution to use'\n default: 'temurin'\nruns:\n using: \"composite\"\n steps:\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0\n with:\n distribution: ${{ inputs.distribution }}\n java-version: 17\n check-latest: true\n - shell: bash\n run: echo \"JDK17=$JAVA_HOME\" >> $GITHUB_ENV # zizmor: ignore[github-env]\n"
},
{
"path": ".github/codecov.yml",
"content": "comment: false\n\ncoverage:\n status:\n project:\n default:\n threshold: \"1\"\n informational: true\n patch: off\n\ncodecov:\n max_report_age: off\n"
},
{
"path": ".github/dco.yml",
"content": "require:\n members: false\n"
},
{
"path": ".github/renovate.json5",
"content": "{\n $schema: 'https://docs.renovatebot.com/renovate-schema.json',\n extends: [\n 'github>junit-team/renovate-config',\n ],\n baseBranchPatterns: [\n 'main',\n 'docs-site'\n ],\n packageRules: [\n {\n matchCurrentValue: '/^2\\\\./',\n allowedVersions: '(,3.0)',\n matchPackageNames: [\n 'org.codehaus.groovy:{/,}**',\n ],\n },\n {\n matchCurrentValue: '/^1\\\\./',\n allowedVersions: '/^1\\\\..*-groovy-2\\\\.*/',\n matchPackageNames: [\n 'org.spockframework:{/,}**',\n ],\n },\n {\n allowedVersions: '!/-SNAPSHOT$/',\n matchPackageNames: [\n 'org.opentest4j.reporting:{/,}**',\n ],\n },\n {\n matchManagers: 'npm',\n matchPackageNames: [\n '@antora/assembler',\n '@antora/html-single-extension',\n '@antora/pdf-extension',\n ],\n \"groupName\": \"@antora/assembler\",\n },\n ],\n}\n"
},
{
"path": ".github/scripts/checkBuildReproducibility.sh",
"content": "#!/bin/bash -e\n\nrm -f checksums-1.txt checksums-2.txt\n\nSOURCE_DATE_EPOCH=$(date +%s)\nexport SOURCE_DATE_EPOCH\n\nfunction calculate_checksums() {\n OUTPUT=$1\n\n ./gradlew \\\n --configuration-cache \\\n --no-build-cache \\\n -Dorg.gradle.java.installations.auto-download=false \\\n -Dscan.tag.Reproducibility \\\n clean \\\n assemble\n\n find . -name '*.jar' \\\n | grep '/build/libs/' \\\n | grep --invert-match 'javadoc' \\\n | sort \\\n | xargs sha512sum > \"${OUTPUT}\"\n}\n\n\ncalculate_checksums checksums-1.txt\ncalculate_checksums checksums-2.txt\n\ndiff checksums-1.txt checksums-2.txt\n"
},
{
"path": ".github/scripts/close-github-milestone.js",
"content": "module.exports = async ({ github, context }) => {\n const releaseVersion = process.env.RELEASE_VERSION;\n const query = `\n query ($owner: String!, $repo: String!, $title: String!) {\n repository(owner: $owner, name: $repo) {\n milestones(first: 100, query: $title) {\n nodes {\n title\n number\n openIssueCount\n }\n }\n }\n }\n `;\n const {repository} = await github.graphql(query, {\n owner: context.repo.owner,\n repo: context.repo.repo,\n title: releaseVersion\n });\n const [milestone] = repository.milestones.nodes.filter(it => it.title === releaseVersion);\n if (!milestone) {\n throw new Error(`Milestone \"${releaseVersion}\" not found`);\n }\n if (milestone.openIssueCount > 0) {\n throw new Error(`Milestone \"${releaseVersion}\" has ${milestone.openIssueCount} open issue(s)`);\n }\n const requestBody = {\n owner: context.repo.owner,\n repo: context.repo.repo,\n milestone_number: milestone.number,\n state: 'closed',\n due_on: new Date().toISOString()\n };\n console.log(requestBody);\n await github.rest.issues.updateMilestone(requestBody);\n};\n"
},
{
"path": ".github/scripts/create-github-release.js",
"content": "module.exports = async ({ github, context }) => {\n const releaseVersion = process.env.RELEASE_VERSION;\n const requestBody = {\n owner: context.repo.owner,\n repo: context.repo.repo,\n tag_name: `r${releaseVersion}`,\n name: `JUnit ${releaseVersion}`,\n generate_release_notes: true,\n body: `JUnit ${releaseVersion} = Platform ${releaseVersion} + Jupiter ${releaseVersion} + Vintage ${releaseVersion}\\n\\nSee [Release Notes](https://docs.junit.org/${releaseVersion}/release-notes.html).`,\n prerelease: releaseVersion.includes(\"-\"),\n };\n console.log(requestBody);\n await github.rest.repos.createRelease(requestBody);\n};\n"
},
{
"path": ".github/scripts/waitForUrl.sh",
"content": "#!/usr/bin/env bash\n\nURL=$1\nprintf 'Waiting for %s' \"$URL\"\nuntil curl --output /dev/null --silent --location --head --fail \"$URL\"; do\n printf '.'\n sleep 5\ndone\necho ' OK'\n"
},
{
"path": ".github/workflows/close-inactive-issues.yml",
"content": "name: Close inactive issues and PRs\non:\n schedule:\n - cron: \"30 1 * * *\"\n workflow_dispatch:\npermissions: {}\njobs:\n close-issues:\n runs-on: ubuntu-latest\n permissions:\n issues: write\n pull-requests: write\n steps:\n - uses: actions/stale@b5d41d4e1d5dceea10e7104786b73624c18a190f # v10.2.0\n with:\n only-labels: \"status: waiting-for-feedback\"\n days-before-stale: 14\n days-before-close: 21\n stale-issue-label: \"status: stale\"\n stale-pr-label: \"status: stale\"\n stale-issue-message: >\n If you would like us to be able to process this issue, please provide the requested information.\n If the information is not provided within the next 3 weeks, we will be unable to proceed and this issue will be closed.\n close-issue-message: >\n Closing due to lack of requested feedback.\n If you would like to proceed with your contribution, please provide the requested information and we will re-open this issue.\n stale-pr-message: >\n If you would like us to be able to process this pull request, please provide the requested information or make the requested changes.\n If the information is not provided or the requested changes are not made within the next 3 weeks, we will be unable to proceed and this pull request will be closed.\n close-pr-message: >\n Closing due to lack of requested feedback.\n If you would like to proceed with your contribution, please provide the requested information or make the requested changes, and we will re-open this pull request.\n"
},
{
"path": ".github/workflows/codeql.yml",
"content": "name: \"CodeQL\"\n\non:\n push:\n branches:\n - main\n - 'releases/**'\n pull_request:\n # The branches below must be a subset of the branches above\n branches:\n - main\n - 'releases/**'\n schedule:\n - cron: '0 19 * * 3'\n\nconcurrency:\n # Cancels in-progress runs only for pull requests\n group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}\n cancel-in-progress: true\n\npermissions: {}\n\nenv:\n DEVELOCITY_ACCESS_KEY: ${{ secrets.DEVELOCITY_ACCESS_KEY }}\n\njobs:\n analyze:\n name: Analyze (${{ matrix.language }})\n runs-on: ubuntu-latest\n permissions:\n security-events: write\n strategy:\n fail-fast: false\n matrix:\n include:\n - language: actions\n build-mode: none\n - language: java-kotlin\n build-mode: manual\n - language: javascript\n build-mode: none\n steps:\n - name: Check out repository\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n persist-credentials: false\n - name: Initialize CodeQL\n uses: github/codeql-action/init@68bde559dea0fdcac2102bfdf6230c5f70eb485e # v4.35.4\n with:\n languages: ${{ matrix.language }}\n build-mode: ${{ matrix.build-mode }}\n tools: linked\n - name: Build\n if: matrix.build-mode == 'manual'\n uses: ./.github/actions/run-gradle\n with:\n encryptionKey: ${{ secrets.GRADLE_ENCRYPTION_KEY }}\n arguments: >-\n --no-build-cache\n -Dscan.tag.CodeQL\n classes\n - name: Perform CodeQL Analysis\n uses: github/codeql-action/analyze@68bde559dea0fdcac2102bfdf6230c5f70eb485e # v4.35.4\n with:\n category: \"/language:${{matrix.language}}\"\n"
},
{
"path": ".github/workflows/cross-version.yml",
"content": "name: Cross-Version\n\non:\n schedule:\n - cron: '0 0 * * 6' # Every Saturday at 00:00 UTC\n push:\n branches:\n - main\n - 'releases/**'\n pull_request:\n branches:\n - '**'\n\nconcurrency:\n # Cancels in-progress runs only for pull requests\n group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}\n cancel-in-progress: true\n\npermissions: {}\n\nenv:\n DEVELOCITY_ACCESS_KEY: ${{ secrets.DEVELOCITY_ACCESS_KEY }}\n\njobs:\n openjdk:\n strategy:\n fail-fast: false\n matrix:\n jdk:\n - version: 26\n type: ga\n - version: 27\n type: ea\n - version: 26\n type: ea\n release: leyden\n - version: 27\n type: ea\n release: valhalla\n name: \"OpenJDK ${{ matrix.jdk.version }} (${{ matrix.jdk.release || matrix.jdk.type }})\"\n runs-on: ubuntu-latest\n steps:\n - name: Check out repository\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n fetch-depth: 1\n persist-credentials: false\n - name: Set up Test JDK\n uses: ./.github/actions/setup-test-jdk\n - name: \"Set up JDK ${{ matrix.jdk.version }} (${{ matrix.jdk.release || 'ea' }})\"\n if: matrix.jdk.type == 'ea'\n uses: oracle-actions/setup-java@fff43251af9936a0e6a4d5d0946e14f1680e9b6b # v1.5.0\n with:\n website: jdk.java.net\n release: ${{ matrix.jdk.release || matrix.jdk.version }}\n version: latest\n - name: \"Set up JDK ${{ matrix.jdk.version }} (${{ matrix.jdk.distribution || 'temurin' }})\"\n if: matrix.jdk.type == 'ga'\n uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0\n with:\n distribution: ${{ matrix.jdk.distribution || 'temurin' }}\n java-version: ${{ matrix.jdk.version }}\n check-latest: true\n - name: 'Prepare JDK${{ matrix.jdk.version }} env var'\n shell: bash\n run: echo \"JDK${{ matrix.jdk.version }}=$JAVA_HOME\" >> $GITHUB_ENV\n - name: Build\n uses: ./.github/actions/run-gradle\n with:\n encryptionKey: ${{ secrets.GRADLE_ENCRYPTION_KEY }}\n # Disable configuration cache due to https://github.com/diffplug/spotless/issues/2318\n arguments: >-\n -Ptesting.enableJaCoCo=false\n -PjavaToolchain.version=${{ matrix.jdk.version }}\n -Dscan.tag.JDK_${{ matrix.jdk.version }}\n build\n --no-configuration-cache\n broken-by-issue: ${{ matrix.jdk.broken-by-issue }}\n - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1\n if: ${{ always() }}\n with:\n name: Open Test Reports (${{ github.job }} ${{ matrix.jdk.version }} (${{ matrix.jdk.release || matrix.jdk.type }}))\n path: '**/build/reports/open-test-report.html'\n openj9:\n strategy:\n fail-fast: false\n matrix:\n jdk: [ 25 ]\n name: \"OpenJ9 ${{ matrix.jdk }}\"\n runs-on: ubuntu-latest\n steps:\n - name: Check out repository\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n fetch-depth: 1\n persist-credentials: false\n - name: Set up Test JDK\n uses: ./.github/actions/setup-test-jdk\n with:\n distribution: semeru\n - name: 'Set up JDK ${{ matrix.jdk }}'\n uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0\n with:\n distribution: semeru\n java-version: ${{ matrix.jdk }}\n check-latest: true\n - name: 'Prepare JDK${{ matrix.jdk }} env var'\n shell: bash\n run: echo \"JDK${{ matrix.jdk }}=$JAVA_HOME\" >> $GITHUB_ENV\n - name: Build\n uses: ./.github/actions/run-gradle\n with:\n encryptionKey: ${{ secrets.GRADLE_ENCRYPTION_KEY }}\n # Disable configuration cache due to https://github.com/diffplug/spotless/issues/2318\n arguments: >-\n -Ptesting.enableJaCoCo=false\n -PjavaToolchain.version=${{ matrix.jdk }}\n -PjavaToolchain.implementation=j9\n -Dscan.tag.JDK_${{ matrix.jdk }}\n -Dscan.tag.OpenJ9\n build\n --no-configuration-cache\n - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1\n if: ${{ always() }}\n with:\n name: Open Test Reports (${{ github.job }})\n path: '**/build/reports/open-test-report.html'\n"
},
{
"path": ".github/workflows/deploy-docs.yml",
"content": "name: Deploy Documentation\n\non: [ workflow_call, workflow_dispatch ]\n\npermissions: {}\n\njobs:\n deploy_documentation:\n name: Deploy Documentation\n runs-on: ubuntu-slim\n permissions:\n actions: write\n steps:\n - name: Trigger documentation site deployment\n uses: nick-fields/retry@ad984534de44a9489a53aefd81eb77f87c70dc60 # v4.0.0\n env:\n GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n with:\n max_attempts: 10\n retry_wait_seconds: 5\n timeout_seconds: 20\n command: gh workflow run deploy-docs.yml --repo junit-team/junit-framework --ref docs-site\n"
},
{
"path": ".github/workflows/gradle-dependency-submission.yml",
"content": "name: Gradle Dependency Submission\n\non:\n push:\n branches:\n - main\n\npermissions: {}\n\nenv:\n DEVELOCITY_ACCESS_KEY: ${{ secrets.DEVELOCITY_ACCESS_KEY }}\n\njobs:\n dependency-submission:\n if: github.repository == 'junit-team/junit-framework'\n runs-on: ubuntu-latest\n permissions:\n contents: write\n steps:\n - name: Check out repository\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n fetch-depth: 1\n persist-credentials: false\n - name: Setup Java\n uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0\n with:\n distribution: temurin\n java-version: 25\n check-latest: true\n - name: Generate and submit dependency graph\n id: dependency-submission\n uses: gradle/actions/dependency-submission@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0\n continue-on-error: true\n - name: Generate and submit dependency graph (retry)\n if: steps.dependency-submission.outcome == 'failure'\n uses: gradle/actions/dependency-submission@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0\n"
},
{
"path": ".github/workflows/label-opened-issues.yml",
"content": "name: Add label to opened issues\non:\n issues:\n types:\n - opened\npermissions: {}\njobs:\n label_issues:\n runs-on: ubuntu-latest\n permissions:\n issues: write\n steps:\n - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0\n with:\n script: |\n const issue = await github.rest.issues.get({\n issue_number: context.issue.number,\n owner: context.repo.owner,\n repo: context.repo.repo,\n });\n const originalLabels = issue.data.labels.map(l => l.name);\n const statusLabels = originalLabels.filter(l => l.startsWith(\"status: \"));\n if (statusLabels.length === 0 && !originalLabels.includes(\"up-for-grabs\")) {\n github.rest.issues.addLabels({\n issue_number: context.issue.number,\n owner: context.repo.owner,\n repo: context.repo.repo,\n labels: [\"status: new\"]\n })\n }\n"
},
{
"path": ".github/workflows/label-pull-request.yml",
"content": "name: Copy labels from linked issues to PR\n\non:\n pull_request_target:\n types: [opened, reopened] # zizmor: ignore[dangerous-triggers]\n\npermissions: {}\n\njobs:\n copy_labels:\n name: Copy labels\n runs-on: ubuntu-latest\n permissions:\n pull-requests: write\n steps:\n - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0\n with:\n script: |\n const query = `\n query($owner: String!, $repo: String!, $pr: Int!) {\n repository(owner: $owner, name: $repo) {\n pullRequest(number: $pr) {\n closingIssuesReferences(first: 10) {\n nodes {\n labels(first: 100) {\n nodes {\n name\n }\n }\n }\n }\n }\n }\n }\n `;\n \n const {repository} = await github.graphql(query, {\n owner: context.repo.owner,\n repo: context.repo.repo,\n pr: context.issue.number\n });\n \n let labels = Array.from(new Set(repository.pullRequest.closingIssuesReferences.nodes\n .flatMap((node) => node.labels.nodes.map((label) => label.name))))\n .filter((label) => !label.startsWith(\"status:\") && label !== \"up-for-grabs\");\n \n if (labels.length > 0) {\n console.log(`Adding labels to PR: ${labels}`);\n await github.rest.issues.addLabels({\n issue_number: context.issue.number,\n owner: context.repo.owner,\n repo: context.repo.repo,\n labels: labels\n });\n }\n"
},
{
"path": ".github/workflows/lock-resolved-issues.yml",
"content": "name: Lock resolved issues\n\non:\n schedule:\n - cron: \"39 1 * * 0\"\n workflow_dispatch:\n\npermissions: {}\n\nconcurrency:\n group: lock-resolved-issues\n\njobs:\n action:\n runs-on: ubuntu-latest\n permissions:\n issues: write\n pull-requests: write\n discussions: write\n steps:\n - uses: dessant/lock-threads@7266a7ce5c1df01b1c6db85bf8cd86c737dadbe7 # v6.0.0\n with:\n process-only: issues\n log-output: true\n"
},
{
"path": ".github/workflows/main.yml",
"content": "name: CI\n\non:\n push:\n branches:\n - main\n - 'releases/**'\n tags-ignore:\n - '**'\n pull_request:\n branches:\n - '**'\n\nconcurrency:\n # Cancels in-progress runs only for pull requests\n group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}\n cancel-in-progress: true\n\npermissions: {}\n\nenv:\n DEVELOCITY_ACCESS_KEY: ${{ secrets.DEVELOCITY_ACCESS_KEY }}\n\njobs:\n Linux:\n runs-on: ubuntu-latest\n steps:\n - name: Check out repository\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n fetch-depth: 1\n persist-credentials: false\n - name: Install GraalVM\n uses: graalvm/setup-graalvm@bef4b0e916c7dd079bf60fb95d49139f67e32c5f # v1.5.3\n with:\n distribution: graalvm\n version: latest\n java-version: 21\n - name: Build\n uses: ./.github/actions/main-build\n with:\n encryptionKey: ${{ secrets.GRADLE_ENCRYPTION_KEY }}\n # Disable configuration cache due to https://github.com/diffplug/spotless/issues/2318\n arguments: >-\n :platform-tooling-support-tests:test\n build\n jacocoRootReport\n --no-configuration-cache\n - name: Upload to Codecov.io\n uses: codecov/codecov-action@57e3a136b779b570ffcdbf80b3bdc90e7fab3de2 # v6.0.0\n with:\n token: ${{ secrets.CODECOV_TOKEN }}\n\n Windows:\n runs-on: windows-latest\n steps:\n - name: Check out repository\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n fetch-depth: 1\n persist-credentials: false\n - name: Build\n uses: ./.github/actions/main-build\n with:\n encryptionKey: ${{ secrets.GRADLE_ENCRYPTION_KEY }}\n\n macOS:\n runs-on: macos-latest\n steps:\n - name: Check out repository\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n fetch-depth: 1\n persist-credentials: false\n - name: Build\n uses: ./.github/actions/main-build\n with:\n encryptionKey: ${{ secrets.GRADLE_ENCRYPTION_KEY }}\n\n publish_artifacts:\n name: Publish Snapshot Artifacts\n needs: macOS\n runs-on: ubuntu-latest\n permissions:\n attestations: write # required for build provenance attestation\n id-token: write # required for build provenance attestation\n if: github.event_name == 'push' && github.repository == 'junit-team/junit-framework' && (startsWith(github.ref, 'refs/heads/releases/') || github.ref == 'refs/heads/main')\n steps:\n - name: Check out repository\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n fetch-depth: 1\n persist-credentials: false\n - name: Publish\n uses: ./.github/actions/run-gradle\n env:\n ORG_GRADLE_PROJECT_mavenCentralUsername: ${{ secrets.MAVEN_CENTRAL_USERNAME }}\n ORG_GRADLE_PROJECT_mavenCentralPassword: ${{ secrets.MAVEN_CENTRAL_PASSWORD }}\n with:\n encryptionKey: ${{ secrets.GRADLE_ENCRYPTION_KEY }}\n arguments: >-\n publishAggregationToCentralSnapshots\n prepareGitHubAttestation\n -x check\n - name: Generate build provenance attestations\n uses: actions/attest@59d89421af93a897026c735860bf21b6eb4f7b26 # v4.1.0\n with:\n subject-path: documentation/build/attestation/*.jar\n\n build_documentation:\n name: Build Documentation\n needs: macOS\n runs-on: ubuntu-latest\n steps:\n - name: Check out repository\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n fetch-depth: 1\n persist-credentials: false\n - name: Install Graphviz\n run: |\n sudo apt-get update\n sudo apt-get install graphviz\n - name: Install Node.js\n uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0\n with:\n node-version-file: documentation/.tool-versions\n - name: Build Documentation\n uses: ./.github/actions/run-gradle\n with:\n encryptionKey: ${{ secrets.GRADLE_ENCRYPTION_KEY }}\n arguments: >-\n antora\n -Pantora.downloadNode=false\n -Dscan.tag.Documentation\n\n deploy_documentation:\n name: Deploy Documentation\n needs: build_documentation\n if: github.event_name == 'push' && github.repository == 'junit-team/junit-framework' && github.ref == 'refs/heads/main'\n uses: ./.github/workflows/deploy-docs.yml\n permissions:\n actions: write\n"
},
{
"path": ".github/workflows/ossf-scorecard.yml",
"content": "name: OpenSSF Scorecard supply-chain security analysis\n\non:\n branch_protection_rule:\n schedule:\n - cron: '31 20 * * 6'\n push:\n branches: [ \"main\" ]\n\npermissions: {}\n\njobs:\n analysis:\n name: Scorecard analysis\n runs-on: ubuntu-latest\n permissions:\n # Needed to upload the results to code-scanning dashboard.\n security-events: write\n # Needed to publish results and get a badge (see publish_results below).\n id-token: write\n\n steps:\n - name: \"Checkout code\"\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n persist-credentials: false\n\n - name: \"Run analysis\"\n uses: ossf/scorecard-action@4eaacf0543bb3f2c246792bd56e8cdeffafb205a # v2.4.3\n with:\n results_file: results.sarif\n results_format: sarif\n # (Optional) \"write\" PAT token. Uncomment the `repo_token` line below if:\n # - you want to enable the Branch-Protection check on a *public* repository, or\n # - you are installing Scorecard on a *private* repository\n # To create the PAT, follow the steps in https://github.com/ossf/scorecard-action?tab=readme-ov-file#authentication-with-fine-grained-pat-optional.\n # repo_token: ${{ secrets.SCORECARD_TOKEN }}\n\n # Public repositories:\n # - Publish results to OpenSSF REST API for easy access by consumers\n # - Allows the repository to include the Scorecard badge.\n # - See https://github.com/ossf/scorecard-action#publishing-results.\n # For private repositories:\n # - `publish_results` will always be set to `false`, regardless\n # of the value entered here.\n publish_results: true\n\n # Upload the results as artifacts (optional). Commenting out will disable uploads of run results in SARIF\n # format to the repository Actions tab.\n - name: \"Upload artifact\"\n uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1\n with:\n name: SARIF file\n path: results.sarif\n retention-days: 5\n\n # Upload the results to GitHub's code scanning dashboard (optional).\n # Commenting out will disable upload of results to your repo's Code Scanning dashboard\n - name: \"Upload to code-scanning\"\n uses: github/codeql-action/upload-sarif@68bde559dea0fdcac2102bfdf6230c5f70eb485e # v4.35.4\n with:\n sarif_file: results.sarif\n"
},
{
"path": ".github/workflows/release.yml",
"content": "name: Release\n\non:\n workflow_dispatch:\n inputs:\n releaseVersion:\n description: Version to be released (e.g. \"5.12.0-M1\")\n required: true\n deploymentId:\n description: ID of the Maven Central Publish Portal deployment\n required: true\n dryRun:\n type: boolean\n description: Enable dry-run mode\n required: false\n default: false\n\npermissions: {}\n\nenv:\n DEVELOCITY_ACCESS_KEY: ${{ secrets.DEVELOCITY_ACCESS_KEY }}\n STAGING_REPO_URL: https://central.sonatype.com/api/v1/publisher/deployment/${{ inputs.deploymentId }}/download\n RELEASE_TAG: r${{ inputs.releaseVersion }}\n RELEASE_VERSION: ${{ inputs.releaseVersion }}\n\njobs:\n\n verify_reproducibility:\n name: Verify reproducibility\n runs-on: ubuntu-latest\n permissions:\n attestations: write # required for build provenance attestation\n id-token: write # required for build provenance attestation\n steps:\n - name: Check out repository\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n fetch-depth: 1\n ref: \"refs/tags/${{ env.RELEASE_TAG }}\"\n persist-credentials: false\n - name: Prepare Maven Central user token\n uses: ./.github/actions/maven-central-user-token\n with:\n username: ${{ secrets.MAVEN_CENTRAL_USERNAME }}\n password: ${{ secrets.MAVEN_CENTRAL_PASSWORD }}\n - name: Download reference JAR from staging repository\n id: referenceJar\n run: |\n curl --silent --fail --location --output /tmp/reference.jar \\\n --header \"Authorization: Bearer $MAVEN_CENTRAL_USER_TOKEN\" \\\n \"${STAGING_REPO_URL}/org/junit/jupiter/junit-jupiter-api/${RELEASE_VERSION}/junit-jupiter-api-${RELEASE_VERSION}.jar\"\n sudo apt-get update && sudo apt-get install --yes jc\n unzip -c /tmp/reference.jar META-INF/MANIFEST.MF | jc --jar-manifest | jq '.[0]' > /tmp/manifest.json\n echo \"createdBy=$(jq --raw-output .Created_By /tmp/manifest.json)\" >> \"$GITHUB_OUTPUT\"\n echo \"buildTimestamp=$(jq --raw-output .Build_Date /tmp/manifest.json) $(jq --raw-output .Build_Time /tmp/manifest.json)\" >> \"$GITHUB_OUTPUT\"\n - name: Verify artifacts\n uses: ./.github/actions/run-gradle\n with:\n encryptionKey: ${{ secrets.GRADLE_ENCRYPTION_KEY }}\n arguments: >-\n --rerun-tasks\n -Pmanifest.buildTimestamp=\"${{ steps.referenceJar.outputs.buildTimestamp }}\"\n -Pmanifest.createdBy=\"${{ steps.referenceJar.outputs.createdBy }}\"\n :verifyArtifactsInStagingRepositoryAreReproducible\n --remote-repo-url=${{ env.STAGING_REPO_URL }}\n - name: Generate build provenance attestations\n if: ${{ inputs.dryRun == false }}\n uses: actions/attest@59d89421af93a897026c735860bf21b6eb4f7b26 # v4.1.0\n with:\n subject-path: build/repo/**/*.jar\n\n verify_consumability:\n name: Verify consumability\n runs-on: ubuntu-latest\n steps:\n - name: Check out repository\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n fetch-depth: 1\n ref: \"refs/tags/${{ env.RELEASE_TAG }}\"\n path: junit-framework\n persist-credentials: false\n - name: Check out examples repository\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n repository: ${{ github.repository_owner }}/junit-examples\n token: ${{ secrets.JUNIT_BUILDS_GITHUB_TOKEN_EXAMPLES_REPO }}\n fetch-depth: 1\n path: junit-examples\n persist-credentials: false\n - name: Set up JDK\n uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0\n with:\n java-version: 25\n distribution: temurin\n - uses: sbt/setup-sbt@93e926cbdb4a428e41b4ef754124ec82925ffdc2 # v1.1.23\n - name: Update JUnit dependencies in examples\n run: java src/Updater.java ${RELEASE_VERSION}\n working-directory: junit-examples\n - name: Prepare Maven Central user token\n uses: ./junit-framework/.github/actions/maven-central-user-token\n with:\n username: ${{ secrets.MAVEN_CENTRAL_USERNAME }}\n password: ${{ secrets.MAVEN_CENTRAL_PASSWORD }}\n - name: Inject staging repository URL\n run: java src/StagingRepoInjector.java ${STAGING_REPO_URL}\n working-directory: junit-examples\n - name: Build examples\n run: java src/Builder.java --exclude=junit-jupiter-starter-bazel,junit-jupiter-starter-sbt,junit-source-launcher\n working-directory: junit-examples\n env:\n MAVEN_ARGS: --settings ${{ github.workspace }}/junit-examples/src/central-staging-maven-settings.xml --activate-profiles central-staging\n\n close_github_milestone:\n name: Close GitHub milestone\n runs-on: ubuntu-latest\n permissions:\n issues: write\n steps:\n - name: Check out repository\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n fetch-depth: 1\n persist-credentials: false\n - name: Close GitHub milestone\n if: ${{ inputs.dryRun == false }}\n uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0\n with:\n result-encoding: string\n script: |\n const closeGithubMilestone = require('./.github/scripts/close-github-milestone.js');\n closeGithubMilestone({ github, context });\n\n publish_deployment:\n name: Publish to Maven Central\n needs: [ verify_reproducibility, verify_consumability, close_github_milestone ]\n runs-on: ubuntu-latest\n steps:\n - name: Check out repository\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n fetch-depth: 1\n ref: \"refs/tags/${{ env.RELEASE_TAG }}\"\n persist-credentials: false\n - name: Release staging repository\n if: ${{ inputs.dryRun == false }}\n uses: ./.github/actions/run-gradle\n env:\n ORG_GRADLE_PROJECT_mavenCentralUsername: ${{ secrets.MAVEN_CENTRAL_USERNAME }}\n ORG_GRADLE_PROJECT_mavenCentralPassword: ${{ secrets.MAVEN_CENTRAL_PASSWORD }}\n with:\n encryptionKey: ${{ secrets.GRADLE_ENCRYPTION_KEY }}\n arguments: nmcpPublishDeployment -PnmcpDeploymentId=${{ inputs.deploymentId }}\n\n publish_documentation:\n name: Publish documentation\n needs: publish_deployment\n runs-on: ubuntu-latest\n permissions:\n actions: write\n steps:\n - name: Check out repository\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n fetch-depth: 1\n persist-credentials: false\n - name: Trigger deployment\n env:\n GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n run: gh workflow run deploy-docs.yml --repo junit-team/junit-framework --ref docs-site\n - name: Install Poppler (for pdfinfo)\n run: |\n sudo apt-get update\n sudo apt-get install --yes poppler-utils\n - name: Wait for deployment\n if: ${{ inputs.dryRun == false }}\n timeout-minutes: 30\n run: ./.github/scripts/waitForUrl.sh \"${URL}\"\n env:\n URL: https://docs.junit.org/${{ inputs.releaseVersion }}/\n - name: Verify integrity of PDF version of User Guide\n if: inputs.dryRun == false && !contains(inputs.releaseVersion, '-')\n run: |\n curl --silent --fail --location --output /tmp/junit-user-guide.pdf \"${PDF_URL}\"\n pdfinfo /tmp/junit-user-guide.pdf\n env:\n PDF_URL: https://docs.junit.org/${{ inputs.releaseVersion }}/_exports/junit-user-guide-${{ inputs.releaseVersion }}.pdf\n\n update_examples:\n name: Update examples\n needs: publish_deployment\n runs-on: ubuntu-latest\n steps:\n - name: Check out examples repository\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n repository: ${{ github.repository_owner }}/junit-examples\n token: ${{ secrets.JUNIT_BUILDS_GITHUB_TOKEN_EXAMPLES_REPO }}\n persist-credentials: true\n - name: Set up JDK\n uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0\n with:\n java-version: 25\n distribution: temurin\n - uses: sbt/setup-sbt@93e926cbdb4a428e41b4ef754124ec82925ffdc2 # v1.1.23\n - name: Update JUnit dependencies in examples\n run: java src/Updater.java ${RELEASE_VERSION}\n - name: Build examples\n if: ${{ inputs.dryRun == false }}\n run: java src/Builder.java\n - name: Create release branch\n run: |\n git config user.name \"JUnit Team\"\n git config user.email \"team@junit.org\"\n git switch -c \"${RELEASE_TAG}\"\n git status\n git commit -a -m \"Use ${RELEASE_VERSION}\"\n - name: Push release branch\n if: ${{ inputs.dryRun == false }}\n run: |\n git push origin \"${RELEASE_TAG}\"\n - name: Update main branch (only for GA releases)\n if: ${{ inputs.dryRun == false && !contains(inputs.releaseVersion, '-') }}\n run: |\n git fetch origin main\n git switch main\n git merge --ff-only \"${RELEASE_TAG}\"\n git push origin main\n\n create_github_release:\n name: Create GitHub release\n if: ${{ inputs.dryRun == false }}\n needs: [ publish_documentation, update_examples ]\n runs-on: ubuntu-latest\n permissions:\n contents: write\n steps:\n - name: Check out repository\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n fetch-depth: 1\n persist-credentials: false\n - name: Create GitHub release\n uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0\n with:\n script: |\n const createGithubRelease = require('./.github/scripts/create-github-release.js');\n createGithubRelease({ github, context });\n"
},
{
"path": ".github/workflows/reproducible-build.yml",
"content": "name: Reproducible build\n\non:\n push:\n branches:\n - main\n - 'releases/**'\n pull_request:\n branches:\n - '**'\n\nconcurrency:\n # Cancels in-progress runs only for pull requests\n group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}\n cancel-in-progress: true\n\npermissions: {}\n\nenv:\n DEVELOCITY_ACCESS_KEY: ${{ secrets.DEVELOCITY_ACCESS_KEY }}\n\njobs:\n check_build_reproducibility:\n name: 'Check build reproducibility'\n runs-on: ubuntu-latest\n steps:\n - name: Check out repository\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n fetch-depth: 1\n persist-credentials: false\n - name: Restore Gradle cache and display toolchains\n uses: ./.github/actions/run-gradle\n with:\n encryptionKey: ${{ secrets.GRADLE_ENCRYPTION_KEY }}\n # Disable configuration cache due to https://github.com/diffplug/spotless/issues/2318\n arguments: >-\n --quiet\n --no-configuration-cache\n - name: Build and compare checksums\n shell: bash\n run: ./.github/scripts/checkBuildReproducibility.sh\n"
},
{
"path": ".github/workflows/sanitize-closed-issues.yml",
"content": "name: Sanitizes assigned labels and milestone on closed issues\non:\n issues:\n types:\n - closed\npermissions: {}\njobs:\n label_issues:\n runs-on: ubuntu-latest\n permissions:\n issues: write\n steps:\n - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0\n with:\n script: |\n const issue = await github.rest.issues.get({\n issue_number: context.issue.number,\n owner: context.repo.owner,\n repo: context.repo.repo,\n });\n const originalLabels = issue.data.labels.map(l => l.name);\n const newLabels = originalLabels.filter(l => l !== \"status: in progress\" && l !== \"status: new\" && l !== \"status: waiting-for-feedback\" && l !== \"status: waiting-for-interest\");\n if (newLabels.length !== originalLabels.length) {\n await github.rest.issues.update({\n issue_number: issue.data.number,\n owner: context.repo.owner,\n repo: context.repo.repo,\n labels: newLabels,\n });\n }\n if (issue.data.state_reason === \"not_planned\" || issue.data.state_reason === \"duplicate\") {\n if (issue.data.milestone) {\n await github.rest.issues.update({\n issue_number: issue.data.number,\n owner: context.repo.owner,\n repo: context.repo.repo,\n milestone: null,\n });\n }\n const statusLabels = newLabels.filter(l => l.startsWith(\"status: \"));\n if (statusLabels.length === 0) {\n if (issue.data.state_reason === \"not_planned\") {\n await github.rest.issues.createComment({\n issue_number: issue.data.number,\n owner: context.repo.owner,\n repo: context.repo.repo,\n body: \"Please assign a status label to this issue.\",\n });\n await github.rest.issues.update({\n issue_number: issue.data.number,\n owner: context.repo.owner,\n repo: context.repo.repo,\n state: \"open\",\n });\n } else {\n newLabels.push(\"status: duplicate\");\n await github.rest.issues.update({\n issue_number: issue.data.number,\n owner: context.repo.owner,\n repo: context.repo.repo,\n labels: newLabels,\n });\n }\n }\n } else {\n if (!(newLabels.includes(\"type: task\") || newLabels.includes(\"type: question\")) && !issue.data.milestone) {\n let collaborator;\n try {\n await github.rest.repos.checkCollaborator({\n owner: context.repo.owner,\n repo: context.repo.repo,\n username: context.actor,\n });\n collaborator = true;\n } catch (error) {\n collaborator = false;\n }\n if (collaborator) {\n await github.rest.issues.createComment({\n issue_number: issue.data.number,\n owner: context.repo.owner,\n repo: context.repo.repo,\n body: \"Please assign a milestone to this issue or label it with `type: task` or `type: question` – or assign a status label and close it as _not planned_.\",\n });\n await github.rest.issues.update({\n issue_number: issue.data.number,\n owner: context.repo.owner,\n repo: context.repo.repo,\n state: \"open\",\n });\n } else {\n const statusLabels = newLabels.filter(l => l.startsWith(\"status: \"));\n if (statusLabels.length === 0) {\n newLabels.push(\"status: invalid\");\n }\n await github.rest.issues.update({\n issue_number: issue.data.number,\n owner: context.repo.owner,\n repo: context.repo.repo,\n labels: newLabels,\n state: \"closed\",\n state_reason: \"not_planned\",\n });\n }\n }\n }\n"
},
{
"path": ".github/workflows/zizmor-analysis.yml",
"content": "name: GitHub Actions Security Analysis\n\non:\n push:\n branches:\n - main\n - 'releases/**'\n paths:\n - '.github/**'\n pull_request:\n paths:\n - '.github/**'\n\npermissions: {}\n\njobs:\n zizmor:\n name: Run zizmor 🌈\n runs-on: ubuntu-latest\n permissions:\n security-events: write\n steps:\n - name: Checkout repository\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n persist-credentials: false\n\n - name: Run zizmor 🌈\n uses: zizmorcore/zizmor-action@b1d7e1fb5de872772f31590499237e7cce841e8e # v0.5.3\n"
},
{
"path": ".github/zizmor.yml",
"content": "rules:\n cache-poisoning:\n ignore:\n # reports issues for setup-node which isn't used while releasing\n - main.yml\n secrets-outside-env:\n disable: true\n"
},
{
"path": ".gitignore",
"content": "# Gradle\n.gradle\n.kotlin\nbuild\n\n# Ignore Gradle GUI config\ngradle-app.setting\n\n# Eclipse\n.classpath\n.settings/\n.project\n/bin/\n/*/bin\n/gradle/plugins/*/bin\n\n# IntelliJ\n*.iml\n*.ipr\n*.iws\n*.uml\n**/.idea/*\n!/.idea/icon.png\n!/.idea/vcs.xml\n/out/\n/*/out/\n\n# Misc\n*.log\n*.graphml\ncoverage.db*\n.metadata\n/.sdkmanrc\n/.tool-versions\n\nchecksums*\n\n# snapshot-tests\n*.snapshot_actual\n*.snapshot_raw\n\n# Antora\n/documentation/node_modules/\n"
},
{
"path": ".idea/vcs.xml",
"content": "\n\n \n \n \n \n \n \n \n \n \n \n \n
\n \n \n \n \n "
},
{
"path": ".jitpack.yml",
"content": "before_install:\n - sdk update\n - sdk install java 25-open\n - sdk use java 25-open\ninstall:\n - |\n ./gradlew \\\n --show-version \\\n -Pjitpack.version=$VERSION \\\n -Ppublishing.group=$GROUP.$ARTIFACT \\\n -Ppublishing.signArtifacts=false \\\n javaToolchains \\\n publishToMavenLocal\n"
},
{
"path": "CONTRIBUTING.md",
"content": "# Contributing\n\n## Getting Started\n\nWe welcome new contributors to the project!\nIf you're interested, please check for [issues labeled with `up-for-grabs`\nthat are not yet in progress](https://github.com/junit-team/junit-framework/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20label%3Aup-for-grabs%20-label%3A%22status%3A%20in%20progress%22).\nGenerally, before you work on an issue, post a comment and ask whether it can be started.\nPlease wait for the core team to respond and assign the issue to you before making any code\nchanges.\n\n## JUnit Contributor License Agreement\n\n- You will only Submit Contributions where You have authored 100% of the content.\n- You will only Submit Contributions to which You have the necessary rights. This means\n that if You are employed You have received the necessary permissions from Your employer\n to make the Contributions.\n- Whatever content You Contribute will be provided under the Project License(s).\n\n### Project Licenses\n\n- All modules use [Eclipse Public License v2.0](LICENSE.md).\n\n## Commit Messages\n\nAs a general rule, the style and formatting of commit messages should follow the guidelines in\n[How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/).\n\nIn addition, any commit that is related to an existing issue must reference the issue.\nFor example, if a commit in a pull request addresses issue \\#999, it must contain the\nfollowing at the bottom of the commit message.\n\n```\nIssue: #999\n```\n\n## Pull Requests\n\nOur [Definition of Done](https://github.com/junit-team/junit-framework/wiki/Definition-of-Done)\n(DoD) offers some guidelines on what we expect from a pull request.\nFeel free to open a pull request that does not fulfill all criteria, e.g. to discuss\na certain change before polishing it, but please be aware that we will only merge it\nonce the DoD is met.\n\nPlease add the following lines to your pull request description:\n\n```markdown\n---\n\nI hereby agree to the terms of the JUnit Contributor License Agreement.\n```\n\n## Coding Conventions\n\n### Naming Conventions\n\nAcronyms are words.\n\nWhenever an acronym is included as part of a type name or method name, keep the first\nletter of the acronym uppercase and use lowercase for the rest of the acronym. Otherwise,\nit becomes _impossible_ to perform camel-cased searches in IDEs, and it becomes\npotentially very difficult for mere humans to read or reason about the element without\nreading documentation (if documentation even exists).\n\nConsider for example a use case needing to support an HTTP URL. Calling the method\n`getHTTPURL()` is absolutely horrible in terms of usability; whereas, `getHttpUrl()` is\ngreat in terms of usability. The same applies for types `HTTPURLProvider` vs\n`HttpUrlProvider`, etc.\n\nWhenever an acronym is included as part of a field name or parameter name:\n\n- If the acronym comes at the start of the field or parameter name, use lowercase for the\n entire acronym -- for example, `String url;`.\n- Otherwise, keep the first letter of the acronym uppercase and use lowercase for the\n rest of the acronym -- for example, `String defaultUrl;`.\n\n### Formatting\n\n#### Code\n\nCode formatting is enforced using the [Spotless](https://github.com/diffplug/spotless)\nGradle plugin. You can use `gradle spotlessApply` to format new code and add missing\nlicense headers to source files. Formatter and import order settings for Eclipse are\navailable in the repository under\n[junit-eclipse-formatter-settings.xml](gradle/config/eclipse/junit-eclipse-formatter-settings.xml)\nand [junit-eclipse.importorder](gradle/config/eclipse/junit-eclipse.importorder),\nrespectively. For IntelliJ IDEA there's a\n[plugin](https://plugins.jetbrains.com/plugin/6546) you can use in conjunction with the\nEclipse settings.\n\nIt is forbidden to use _wildcard imports_ (e.g., `import static org.junit.jupiter.api.Assertions.*;`)\nin Java code.\n\n#### Documentation\n\nText in `*.adoc` and `*.md` files should be wrapped at 90 characters whenever technically\npossible.\n\nIn multi-line bullet point entries, subsequent lines should be indented.\n\n### Spelling\n\nUse American English spelling rules when writing documentation as well as for\ncode -- class names, method names, variable names, etc.\n\n### Javadoc\n\n- Javadoc comments should be wrapped after 80 characters whenever possible.\n- This first paragraph must be a single, concise sentence that ends with a period (`.`).\n- Place `` on the same line as the first line of a new paragraph and precede `
` with a blank line.\n- Insert a blank line before at-clauses/tags.\n- Favor `{@code foo}` over `foo`.\n- Favor literals (e.g., `{@literal @}`) over HTML entities.\n- New classes and methods should declare a `@since ...` tag.\n- Use `@since 5.10` instead of `@since 5.10.0`.\n- Do not use `@author` tags. Instead, contributors are listed on the [GitHub](https://github.com/junit-team/junit-framework/graphs/contributors) page.\n- Do not use verbs in third-person form in the first sentence of the Javadoc for a method -- for example, use \"Discover tests...\" instead of \"Discovers tests...\".\n\n#### Examples\n\nSee [`ExtensionContext`](junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/ExtensionContext.java) and\n[`ParameterContext`](junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/ParameterContext.java) for example Javadoc.\n\n### Constant fields\n\nA constant field is a `static final` field whose value is immutable. If a static final\nfield has a primitive type or an immutable reference type it is a constant field.\n\n- To minimize accessibility and mutability for all non-private `static final` fields\n under `src/main` should be constant fields.\n- Constant fields should be named using uppercase words separated by underscores. For\n example `DEFAULT_HTTP_URL_PROVIDER`.\n\nNote: `org.junit.platform.commons.logging.Logger` is considered mutable.\n\n### Nullability\n\nThis project uses JSpecify's annotation to indicate nullability. In general, the approach\nis as follows:\n\n- All packages are annotated with `@NullMarked`\n- Types of fields, parameters, return types etc. may be annotated with `@Nullable`\n\n### Tests\n\n#### Naming\n\n- All test classes must end with a `Tests` suffix.\n- Example test classes that should not be picked up by the build must end with a `TestCase` suffix.\n\n#### Assertions\n\n- Use `org.junit.jupiter.api.Assertions` for simple assertions.\n- Use AssertJ when richer assertions are needed.\n- Do not use `org.junit.Assert` or `junit.framework.Assert`.\n\n#### Mocking and Stubbing\n\n- Use either [Mockito](https://github.com/mockito/mockito) or hand-written test doubles.\n\n### Logging\n\n- In general, logging should be used sparingly.\n- All logging must be performed via the internal `Logger` façade provided via the JUnit [LoggerFactory](https://github.com/junit-team/junit-framework/blob/main/junit-platform-commons/src/main/java/org/junit/platform/commons/logging/LoggerFactory.java).\n- Levels defined in JUnit's [Logger](https://github.com/junit-team/junit-framework/blob/main/junit-platform-commons/src/main/java/org/junit/platform/commons/logging/Logger.java) façade, which delegates to Java Util Logging (JUL) for the actual logging.\n - _error_ (JUL: `SEVERE`, Log4J: `ERROR`): extra information (in addition to an Exception) about errors that will halt execution\n - _warn_ (JUL: `WARNING`, Log4J: `WARN`): potential usage or configuration errors that should not halt execution\n - _info_ (JUL: `INFO`, Log4J: `INFO`): information the users might want to know but not by default\n - _config_ (JUL: `CONFIG`, Log4J: `CONFIG`): information related to configuration of the system (Example: `ServiceLoaderTestEngineRegistry` logs IDs of discovered engines)\n - _debug_ (JUL: `FINE`, Log4J: `DEBUG`)\n - _trace_ (JUL: `FINER`, Log4J: `TRACE`)\n\n### Deprecation\n\nThe JUnit project uses the `@API` annotation from [API Guardian](https://github.com/apiguardian-team/apiguardian).\nPublicly available interfaces, classes, and methods have a defined lifecycle\nwhich is described in detail in the [User Guide](https://docs.junit.org/current/api-evolution.html).\n\nThat following describes the deprecation process followed for API items.\n\nTo deprecate an item:\n- Update the `@API.status` to `DEPRECATED`.\n- Update `@API.since`. Please note `since` describes the version when the\n status was changed and not the introduction of the element.\n- Add the `@Deprecated` Java annotation on the item.\n- Add the `@deprecated` JavaDoc tag to describe the deprecation, and refer to\n an eventual replacement.\n- If the item is used in existing code, add `@SuppressWarnings(\"deprecation\")`\n to make the build pass.\n\n## Building the Project\n\nPlease refer to [the readme](README.md#building-from-source) and [the documentation readme](documentation/README.md) for\nthe most common build commands.\n\n### Build Cache\n\nLocal builds can reuse outputs from previous CI builds via Gradle's [Build Cache](https://docs.gradle.org/current/userguide/build_cache.html).\nThe default build cache server is located in the US.\nIf you're in Europe, you can configure the build to use a build cache node located in the EU by adding the following to the `gradle.properties` file in your [Gradle user home](https://docs.gradle.org/current/userguide/directory_layout.html#dir:gradle_user_home):\n\n```properties\njunit.develocity.buildCache.server=https://eu-build-cache-ge.junit.org\n```\n\n### Build Parameters\n\nThe build can be influenced by a number of parameters. For example, measuring\nJaCoCo code coverage of Test tasks can be enabled, or Predictive Test Selection\ndisabled. To see the full list, please run the following task:\n\n`./gradlew :plugins:build-parameters:parameters`\n"
},
{
"path": "KEYS",
"content": "This file contains the PGP key that is used to sign releases.\n\nImporting: `pgp < KEYS` or `gpg --import KEYS`\n\nAdding a key:\n`pgp -kxa >> KEYS`,\nor `(pgpk -ll && pgpk -xa ) >> KEYS`,\nor `(gpg --list-sigs && gpg --armor --export ) >> KEYS`\n\n================================\n\npub rsa4096 2018-04-08 [SC]\n FF6E2C001948C5F2F38B0CC385911F425EC61B51\nuid [ unknown] Open Source Development \nsig 3 85911F425EC61B51 2018-04-08 Open Source Development \nsub rsa4096 2018-04-08 [E]\nsig 85911F425EC61B51 2018-04-08 Open Source Development \n\n-----BEGIN PGP PUBLIC KEY BLOCK-----\n\nmQINBFrKW9IBEACkqUvM7hU1WqOOeb1gZ7pUsRliHuoUvYIrd+hdp+qhPmJ0NG0W\nYhZK5UtJBmqvtHKRkbwYxUuya9zlBmCfQFf0GpFKJ65JSrPSkZADI3aZ4aUkxIUw\nnIRoUHucmr10Xftpebr/zaJk5oR8RdaL5FapapmcZmAaHR9CDWB8XtI318u314jq\nM5rKatnAZMERoPugOvvuAOz4bfZKwdfCmZKfYUM/TMSrSinXrGExSW6z4RhtqmpC\nE5M/7OoVfvDynVJKqNazqgigpmMNhOyzAhQsiKh1K0akyxTZbjeZKsdYfhCXvq0q\nk9+KM/cTllQ54MPnFWiObLkHeK0Waw8bI/vAJ4h4x/XM9iGYpkXv7F2/FVsHQdPe\nYJcwD/CkD8KHyiPaRKMeApiUtZsdAHU0L4X/lNmcooea/7ipskruUgwcm+RdLhRZ\nP949t1e7nqDZfpEHy90NiFxmlRAPSNqBLwefxY/hwBgog2jabDALJVcLCMosFWPj\nMQhFlGSIODiVcW8folGIjzkyNZbNMWkwnl2QnWp/h2TAwYQJOMqcv2MG9o5pyzpx\n97Iz1ngq1FlM/gJnGnNUydP2tAjT2L2U3MP1uX/EdRChdgPqdolqYhdFfwCr0Fpf\nW527bUZpReHCEiQ29ABSnQ711mO+d9+qM6edRyHUoBWz89IHt8sCunuvNwARAQAB\ntC1PcGVuIFNvdXJjZSBEZXZlbG9wbWVudCA8bWFpbEBtYXJjcGhpbGlwcC5kZT6J\nAk4EEwEIADgWIQT/biwAGUjF8vOLDMOFkR9CXsYbUQUCWspb0gIbAwULCQgHAgYV\nCAkKCwIEFgIDAQIeAQIXgAAKCRCFkR9CXsYbUQyRD/9xm3BqdpWcRCE5UyB6nbwV\n8TgzMmbOhpFhhcjzobly/pKAbcofKsjhreENJkfBVUo+zAFx21ToC5tbH20wRtIE\nvQVCP6sAIzhYWU1ohafqVFP4+PztNBuYTnS6vGvSwzp0IXLIIoxSxo0IOED9uUS9\nDTxh1n9NnDLDe2pfjrXBblQtLSW3W5ISDoUvcoyO7Hk1OByW6MNsSoLvXIUNeVhB\nju9TfYxFACJSWBhUxJfgip9Y2GrNBJaYGLZrTAoW1Lh1H1DfLV3wHDClQ1+H+oyx\nIOZULEGYY3MgZTd6Ner2yNAUCB7gVa50NiCZXCS74m+XzMrTEsdWjSMUaOe+dL0I\n9MCrgi4ycUHWIfTKx9gGlIOo3hSDMN+8Nj33XPjLT8kcfoFeUX8jTOvC1HFfTuQJ\nx2t/dKHizdrS3F6A/JQa7v8GNTrZFnEXkwgRTf3ccLoo3gPwzNJeCm2xNjvne1VH\nfvxzwNmq8M05oicEigvEed2VMStMhvT7dSiMAf66rEJHjjaHAoNqbLDEATYrWUP2\nI52txHSSxSJohxVP6Ec6dERnqqYi0mVyzBPo7mmFFBisq74w8RvZXyzvXE3BTiDL\nwe1E/Z/AXbtJye9DickQ/G6RFtVLbUHQfzyRS/65JPtlH8rqJr58YWlylGImVLwE\nOsKNQrwLZ0UkfaWV7wqr3rkCDQRaylvSARAAnQG636wliEOLkXN662OZS6Qz2+cF\nltCWboq9oX9FnA1PHnTY2cAtwS214RfWZxkjg6Stau+d1Wb8TsF/SUN3eKRSyrkA\nxlX0v552vj3xmmfNsslQX47e6aEWZ0du0M8jw7/f7Qxp0InkBfpQwjSg4ECoH4cA\n6dOFJIdxBv8dgS4K90HNuIHa+QYfVSVMjGwOjD9St6Pwkbg1sLedITRo59Bbv0J1\n4nE9LdWbCiwNrkDr24jTewdgrDaCpN6msUwcH1E0nYxuKAetHEi2OpgBhaY3RQ6Q\nPQB6NywvmD0xRllMqu4hSp70pHFtm8LvJdWOsJ5we3KijHuZzEbBVTTl+2DhNMI0\nKMoh+P/OmyNOfWD8DL4NO3pVv+mPDZn82/eZ3XY1/oSQrpyJaCBjRKasVTtfiA/F\ngYqTml6qZMjy6iywg84rLezELgcxHHvjhAKd4CfxyuCCgnGT0iRLFZKw44ZmOUqP\nDkyvGRddIyHag1K7UaM/2UMn6iPMy7XWcaFiH5Huhz43SiOdsWGuwNk4dDxHdxmz\nSjps0H5dkfCciOFhEc54AFcGEXCWHXuxVqIq/hwqTmVl1RY+PTcQUIOfx36WW1ix\nJQf8TpVxUbooK8vr1jOFF6khorDXoZDJNhI2VKomWp8Y38EPGyiUPZNcnmSiezx+\nMoQwAbeqjFMKG7UAEQEAAYkCNgQYAQgAIBYhBP9uLAAZSMXy84sMw4WRH0JexhtR\nBQJaylvSAhsMAAoJEIWRH0JexhtR0LEP/RvYGlaokoosAYI5vNORAiYEc1Ow2McP\nI1ZafHhcVxZhlwF48dAC2bYcasDX/PbEdcD6pwo8ZU8eI8Ht0VpRQxeV/sP01m2Y\nEpAuyZ6jI7IQQCGcwQdN4qzQJxMAASl9JlplH2NniXV1/994FOtesT59ePMyexm5\n7lzhYXP1PGcdt8dH37r6z3XQu0lHRG/KBn7YhyA3zwJcno324KdBRJiynlc7uqQq\n+ZptU9fR1+Nx0uoWZoFMsrQUmY34aAOPJu7jGMTG+VseMH6vDdNhhZs9JOlD/e/V\naF7NyadjOUD4j/ud7c0z2EwqjDKMFTHGbIdawT/7jartT+9yGUO+EmScBMiMuJUT\ndCP4YDh3ExRdqefEBff3uE/rAP73ndNYdIVq9U0gY0uSNCD9JPfj4aCN52y9a2pS\n7Dg7KB/Z8SH1R9IWP+t0HvVtAILdsLExNFTedJGHRh7uaC7pwRz01iivmtAKYICz\nruqlJie/IdEFFK/sus6fZek29odTrQxx42HGHO5GCNyEdK9jKVAeuZ10vcaNbuBp\niP7sf8/BsiEU4wHE8gjFeUPRiSjnERgXQwfJosLgf/K/SShQn2dCkYZRNF+SWJ6Z\n2tQxcW5rpUjtclV/bRVkUX21EYfwA6SMB811mI7AVy8WPXCe8La72ukmaxEGbpJ8\nmdzS2PJko7mm\n=l0XA\n-----END PGP PUBLIC KEY BLOCK-----\n"
},
{
"path": "LICENSE.md",
"content": "Eclipse Public License - v 2.0\n==============================\n\nTHE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE PUBLIC LICENSE (“AGREEMENT”). ANY USE, REPRODUCTION OR DISTRIBUTION OF THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT.\n\n### 1. Definitions\n\n“Contribution” means:\n* **a)** in the case of the initial Contributor, the initial content Distributed under this Agreement, and\n* **b)** in the case of each subsequent Contributor:\n\t* **i)** changes to the Program, and\n\t* **ii)** additions to the Program;\nwhere such changes and/or additions to the Program originate from and are Distributed by that particular Contributor. A Contribution “originates” from a Contributor if it was added to the Program by such Contributor itself or anyone acting on such Contributor's behalf. Contributions do not include changes or additions to the Program that are not Modified Works.\n\n“Contributor” means any person or entity that Distributes the Program.\n\n“Licensed Patents” mean patent claims licensable by a Contributor which are necessarily infringed by the use or sale of its Contribution alone or when combined with the Program.\n\n“Program” means the Contributions Distributed in accordance with this Agreement.\n\n“Recipient” means anyone who receives the Program under this Agreement or any Secondary License (as applicable), including Contributors.\n\n“Derivative Works” shall mean any work, whether in Source Code or other form, that is based on (or derived from) the Program and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship.\n\n“Modified Works” shall mean any work in Source Code or other form that results from an addition to, deletion from, or modification of the contents of the Program, including, for purposes of clarity any new file in Source Code form that contains any contents of the Program. Modified Works shall not include works that contain only declarations, interfaces, types, classes, structures, or files of the Program solely in each case in order to link to, bind by name, or subclass the Program or Modified Works thereof.\n\n“Distribute” means the acts of **a)** distributing or **b)** making available in any manner that enables the transfer of a copy.\n\n“Source Code” means the form of a Program preferred for making modifications, including but not limited to software source code, documentation source, and configuration files.\n\n“Secondary License” means either the GNU General Public License, Version 2.0, or any later versions of that license, including any exceptions or additional permissions as identified by the initial Contributor.\n\n### 2. Grant of Rights\n\n**a)** Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, worldwide, royalty-free copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, Distribute and sublicense the Contribution of such Contributor, if any, and such Derivative Works.\n\n**b)** Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, worldwide, royalty-free patent license under Licensed Patents to make, use, sell, offer to sell, import and otherwise transfer the Contribution of such Contributor, if any, in Source Code or other form. This patent license shall apply to the combination of the Contribution and the Program if, at the time the Contribution is added by the Contributor, such addition of the Contribution causes such combination to be covered by the Licensed Patents. The patent license shall not apply to any other combinations which include the Contribution. No hardware per se is licensed hereunder.\n\n**c)** Recipient understands that although each Contributor grants the licenses to its Contributions set forth herein, no assurances are provided by any Contributor that the Program does not infringe the patent or other intellectual property rights of any other entity. Each Contributor disclaims any liability to Recipient for claims brought by any other entity based on infringement of intellectual property rights or otherwise. As a condition to exercising the rights and licenses granted hereunder, each Recipient hereby assumes sole responsibility to secure any other intellectual property rights needed, if any. For example, if a third party patent license is required to allow Recipient to Distribute the Program, it is Recipient's responsibility to acquire that license before distributing the Program.\n\n**d)** Each Contributor represents that to its knowledge it has sufficient copyright rights in its Contribution, if any, to grant the copyright license set forth in this Agreement.\n\n**e)** Notwithstanding the terms of any Secondary License, no Contributor makes additional grants to any Recipient (other than those set forth in this Agreement) as a result of such Recipient's receipt of the Program under the terms of a Secondary License (if permitted under the terms of Section 3).\n\n### 3. Requirements\n\n**3.1** If a Contributor Distributes the Program in any form, then:\n\n* **a)** the Program must also be made available as Source Code, in accordance with section 3.2, and the Contributor must accompany the Program with a statement that the Source Code for the Program is available under this Agreement, and informs Recipients how to obtain it in a reasonable manner on or through a medium customarily used for software exchange; and\n\n* **b)** the Contributor may Distribute the Program under a license different than this Agreement, provided that such license:\n\t* **i)** effectively disclaims on behalf of all other Contributors all warranties and conditions, express and implied, including warranties or conditions of title and non-infringement, and implied warranties or conditions of merchantability and fitness for a particular purpose;\n\t* **ii)** effectively excludes on behalf of all other Contributors all liability for damages, including direct, indirect, special, incidental and consequential damages, such as lost profits;\n\t* **iii)** does not attempt to limit or alter the recipients' rights in the Source Code under section 3.2; and\n\t* **iv)** requires any subsequent distribution of the Program by any party to be under a license that satisfies the requirements of this section 3.\n\n**3.2** When the Program is Distributed as Source Code:\n\n* **a)** it must be made available under this Agreement, or if the Program **(i)** is combined with other material in a separate file or files made available under a Secondary License, and **(ii)** the initial Contributor attached to the Source Code the notice described in Exhibit A of this Agreement, then the Program may be made available under the terms of such Secondary Licenses, and\n* **b)** a copy of this Agreement must be included with each copy of the Program.\n\n**3.3** Contributors may not remove or alter any copyright, patent, trademark, attribution notices, disclaimers of warranty, or limitations of liability (“notices”) contained within the Program from any copy of the Program which they Distribute, provided that Contributors may add their own appropriate notices.\n\n### 4. Commercial Distribution\n\nCommercial distributors of software may accept certain responsibilities with respect to end users, business partners and the like. While this license is intended to facilitate the commercial use of the Program, the Contributor who includes the Program in a commercial product offering should do so in a manner which does not create potential liability for other Contributors. Therefore, if a Contributor includes the Program in a commercial product offering, such Contributor (“Commercial Contributor”) hereby agrees to defend and indemnify every other Contributor (“Indemnified Contributor”) against any losses, damages and costs (collectively “Losses”) arising from claims, lawsuits and other legal actions brought by a third party against the Indemnified Contributor to the extent caused by the acts or omissions of such Commercial Contributor in connection with its distribution of the Program in a commercial product offering. The obligations in this section do not apply to any claims or Losses relating to any actual or alleged intellectual property infringement. In order to qualify, an Indemnified Contributor must: **a)** promptly notify the Commercial Contributor in writing of such claim, and **b)** allow the Commercial Contributor to control, and cooperate with the Commercial Contributor in, the defense and any related settlement negotiations. The Indemnified Contributor may participate in any such claim at its own expense.\n\nFor example, a Contributor might include the Program in a commercial product offering, Product X. That Contributor is then a Commercial Contributor. If that Commercial Contributor then makes performance claims, or offers warranties related to Product X, those performance claims and warranties are such Commercial Contributor's responsibility alone. Under this section, the Commercial Contributor would have to defend claims against the other Contributors related to those performance claims and warranties, and if a court requires any other Contributor to pay any damages as a result, the Commercial Contributor must pay those damages.\n\n### 5. No Warranty\n\nEXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, AND TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE PROGRAM IS PROVIDED ON AN “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Each Recipient is solely responsible for determining the appropriateness of using and distributing the Program and assumes all risks associated with its exercise of rights under this Agreement, including but not limited to the risks and costs of program errors, compliance with applicable laws, damage to or loss of data, programs or equipment, and unavailability or interruption of operations.\n\n### 6. Disclaimer of Liability\n\nEXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, AND TO THE EXTENT PERMITTED BY APPLICABLE LAW, NEITHER RECIPIENT NOR ANY CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.\n\n### 7. General\n\nIf any provision of this Agreement is invalid or unenforceable under applicable law, it shall not affect the validity or enforceability of the remainder of the terms of this Agreement, and without further action by the parties hereto, such provision shall be reformed to the minimum extent necessary to make such provision valid and enforceable.\n\nIf Recipient institutes patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Program itself (excluding combinations of the Program with other software or hardware) infringes such Recipient's patent(s), then such Recipient's rights granted under Section 2(b) shall terminate as of the date such litigation is filed.\n\nAll Recipient's rights under this Agreement shall terminate if it fails to comply with any of the material terms or conditions of this Agreement and does not cure such failure in a reasonable period of time after becoming aware of such noncompliance. If all Recipient's rights under this Agreement terminate, Recipient agrees to cease use and distribution of the Program as soon as reasonably practicable. However, Recipient's obligations under this Agreement and any licenses granted by Recipient relating to the Program shall continue and survive.\n\nEveryone is permitted to copy and distribute copies of this Agreement, but in order to avoid inconsistency the Agreement is copyrighted and may only be modified in the following manner. The Agreement Steward reserves the right to publish new versions (including revisions) of this Agreement from time to time. No one other than the Agreement Steward has the right to modify this Agreement. The Eclipse Foundation is the initial Agreement Steward. The Eclipse Foundation may assign the responsibility to serve as the Agreement Steward to a suitable separate entity. Each new version of the Agreement will be given a distinguishing version number. The Program (including Contributions) may always be Distributed subject to the version of the Agreement under which it was received. In addition, after a new version of the Agreement is published, Contributor may elect to Distribute the Program (including its Contributions) under the new version.\n\nExcept as expressly stated in Sections 2(a) and 2(b) above, Recipient receives no rights or licenses to the intellectual property of any Contributor under this Agreement, whether expressly, by implication, estoppel or otherwise. All rights in the Program not expressly granted under this Agreement are reserved. Nothing in this Agreement is intended to be enforceable by any entity that is not a Contributor or Recipient. No third-party beneficiary rights are created under this Agreement.\n\n#### Exhibit A - Form of Secondary Licenses Notice\n\n> “This Source Code may also be made available under the following Secondary Licenses when the conditions for such availability set forth in the Eclipse Public License, v. 2.0 are satisfied: {name license(s), version(s), and exceptions or additional permissions here}.”\n\nSimply including a copy of this Agreement, including this Exhibit A is not sufficient to license the Source Code under Secondary Licenses.\n\nIf it is not possible or desirable to put the notice in a particular file, then You may include the notice in a location (such as a LICENSE file in a relevant directory) where a recipient would be likely to look for such a notice.\n\nYou may add additional accurate notices of copyright ownership.\n"
},
{
"path": "NOTICE.md",
"content": "Open Source Licenses\n====================\n\nThis product may include a number of subcomponents with separate\ncopyright notices and license terms. Your use of the source code for\nthese subcomponents is subject to the terms and conditions of the\nsubcomponent's license, as noted in the `LICENSE-[.md]`\nfiles.\n"
},
{
"path": "README.md",
"content": "\n \n \n \n \n \n\nThis repository is the home of JUnit Platform, Jupiter, and Vintage.\n\n## Sponsors\n\n[](https://junit.org/sponsoring)\n\n* **Gold Sponsors:** [JetBrains](https://jb.gg/junit-logo), [Netflix](https://www.netflix.com/)\n* **Silver Sponsors:** [Micromata](https://www.micromata.de), [Quo Card](https://quo-digital.jp)\n* **Bronze Sponsors:** [Premium Minds](https://www.premium-minds.com), [codefortynine](https://codefortynine.com), [Info Support](https://www.infosupport.com), [Code Intelligence](https://www.code-intelligence.com), [Route4Me](https://route4me.com/), [Testiny](https://www.testiny.io/), [TestMu AI](https://www.testmuai.com/?utm_medium=sponsor&utm_source=junit)\n\n## Latest Releases\n\n- General Availability (GA): [JUnit 6.0.3](https://github.com/junit-team/junit-framework/releases/tag/r6.0.3) (February 15, 2026)\n- Preview (Milestone/Release Candidate): [JUnit 6.1.0-RC1](https://github.com/junit-team/junit-framework/releases/tag/r6.1.0-RC1) (April 25, 2026)\n\n## Documentation\n\n- [User Guide]\n- [Javadoc]\n- [Release Notes]\n- [Examples]\n\n## Contributing\n\nContributions to JUnit are both welcomed and appreciated. For specific guidelines\nregarding contributions, please see [CONTRIBUTING.md] in the root directory of the\nproject. Those willing to use milestone or SNAPSHOT releases are encouraged\nto file feature requests and bug reports using the project's\n[issue tracker](https://github.com/junit-team/junit-framework/issues). Issues marked with an\n`up-for-grabs` \nlabel are specifically targeted for community contributions.\n\n## Getting Help\n\nAsk JUnit-related questions on [StackOverflow] or use the Q&A category on [GitHub Discussions].\n\n## Continuous Integration Builds\n\n[](https://github.com/junit-team/junit-framework/actions/workflows/main.yml) [](https://github.com/junit-team/junit-framework/actions/workflows/cross-version.yml)\n\nOfficial CI build server used to perform quick checks on submitted pull requests and for\nbuild matrices including the latest released OpenJDK and early access builds of the next\nOpenJDK.\n\n## Code Coverage\n\nCode coverage using [JaCoCo] for the latest build is available on [Codecov].\n\nA code coverage report can also be generated locally via the [Gradle Wrapper] by\nexecuting `./gradlew clean jacocoRootReport`. The results will be available\nin `build/reports/jacoco/jacocoRootReport/html/index.html`.\n\n## Develocity\n\n[](https://ge.junit.org/scans)\n\nJUnit utilizes [Develocity](https://gradle.com/) for [Build Scans](https://scans.gradle.com/),\n[Build Cache](https://docs.gradle.org/current/userguide/build_cache.html), and\n[Predictive Test Selection](https://docs.gradle.com/enterprise/predictive-test-selection/).\n\nThe latest Build Scans are available on [ge.junit.org](https://ge.junit.org/). Currently,\nonly core team members can publish Build Scans on that server.\nYou can, however, publish a Build Scan to [scans.gradle.com](https://scans.gradle.com/) by\nusing the `--scan` parameter explicitly.\n\nThe remote Build Cache is enabled by default for everyone so that local builds can reuse\ntask outputs from previous CI builds.\n\n## Building from Source\n\nYou need [JDK 25] to build JUnit. [Gradle toolchains] are used to detect and\npotentially download additional JDKs for compilation and test execution.\n\nAll modules can be _built_ and _tested_ with the [Gradle Wrapper] using the following command:\n\n`./gradlew build`\n\nAll modules can be _installed_ in a local Maven repository for consumption in other local\nprojects via the following command:\n\n`./gradlew publishToMavenLocal`\n\n## Dependency Metadata\n\n[](https://central.sonatype.com/search?namespace=org.junit.jupiter)\n[](https://central.sonatype.com/search?namespace=org.junit.vintage)\n[](https://central.sonatype.com/search?namespace=org.junit.platform)\n\nConsult the [Dependency Metadata] section of the [User Guide] for a list of all artifacts\nof the JUnit Platform, JUnit Jupiter, and JUnit Vintage.\n\n\n[Codecov]: https://codecov.io/gh/junit-team/junit-framework\n[CONTRIBUTING.md]: https://github.com/junit-team/junit-framework/blob/HEAD/CONTRIBUTING.md\n[Dependency Metadata]: https://docs.junit.org/current/appendix.html#dependency-metadata\n[GitHub Discussions]: https://github.com/junit-team/junit-framework/discussions/categories/q-a\n[Gradle toolchains]: https://docs.gradle.org/current/userguide/toolchains.html\n[Gradle Wrapper]: https://docs.gradle.org/current/userguide/gradle_wrapper.html#sec:using_wrapper\n[JaCoCo]: https://www.eclemma.org/jacoco/\n[Javadoc]: https://api.junit.org\n[JDK 25]: https://javaalmanac.io/jdk/25/\n[Release Notes]: https://docs.junit.org/current/release-notes.html\n[Examples]: https://github.com/junit-team/junit-examples\n[StackOverflow]: https://stackoverflow.com/questions/tagged/junit5\n[User Guide]: https://docs.junit.org\n"
},
{
"path": "RELEASING.md",
"content": "# Releasing\n\n## Pre-release steps\n\n- [ ] Switch or create the release branch for this feature release (e.g. `releases/5.12.x`)\n- [ ] Change `version` in `gradle.properties` to the versions about to be released\n- [ ] Change release date in Release Notes\n- [ ] Change release date in `README.MD`\n- [ ] Commit with message \"Release ${VERSION}\"\n- [ ] Execute `./gradlew --no-build-cache --no-configuration-cache clean build publishAggregationToCentralPortal`\n- [ ] Tag current commit: `git tag -s -m ${VERSION} r${VERSION}`\n- [ ] Change `version` in `gradle.properties` on release branch to new development versions and commit with message \"Back to snapshots for further development\" or similar\n- [ ] Push release branch and tag to GitHub: `git push --set-upstream --follow-tags origin HEAD`\n- [ ] Trigger a [release build](https://github.com/junit-team/junit-framework/actions/workflows/release.yml): `gh workflow run --ref r${VERSION} -f releaseVersion=${VERSION} -f deploymentId=${DEPLOYMENT_ID} release.yml`\n - Select the release branch\n - Enter the version to be released\n - Enter the staging repository ID from the output of above Gradle build\n\n## Post-release steps\n\n- [ ] Post about the new release:\n - [ ] [Mastodon](https://fosstodon.org/@junit)\n - [ ] [Bluesky](https://bsky.app/profile/junit.org)\n\n### Preview releases (milestones and release candidates)\n\n- [ ] Fast-forward merge the release branch to `main` and push to GitHub\n- [ ] Create release notes for the next preview or feature release from the template\n\n### Feature releases (x.y.0)\n\n- [ ] Delete `accepted-breaking-changes.csv` (if it exists), change `previousVersion` in `gradle.properties` to `x.y.0` on the release branch, and commit with message \"Update API baseline and clear accepted breaking changes\"\n- [ ] Fast-forward merge the release branch to `main` and push to GitHub\n- [ ] Update the [security policy](https://github.com/junit-team/junit-framework/blob/main/SECURITY.md) and commit with message \"Update security policy to reflect 5.x release\" or similar\n- [ ] Create release notes for the next feature release from the template\n- [ ] Update [JBang catalog](https://github.com/junit-team/jbang-catalog/blob/main/jbang-catalog.json)\n\n### Patch releases (x.y.z)\n\n- [ ] Cherry-pick the tagged commit from the release branch to `main` and resolve the conflict in `gradle.properties` by choosing the version of the `main` branch\n- [ ] Delete `accepted-breaking-changes.csv` (if it exists), change `previousVersion` in `gradle.properties` to `x.y.z` on the release branch, and commit with message \"Update API baseline and clear accepted breaking changes\"\n- [ ] Include the release notes of the patch release on `main` if not already present\n- [ ] Update [JBang catalog](https://github.com/junit-team/jbang-catalog/blob/main/jbang-catalog.json)\n"
},
{
"path": "SECURITY.md",
"content": "# Security Policy\n\n[](https://www.bestpractices.dev/projects/9607) [](https://scorecard.dev/viewer/?uri=github.com/junit-team/junit-framework)\n\n## JAR Signing\n\nJUnit JARs released on Maven Central are signed.\nYou'll find more information about the key here: [KEYS](./KEYS)\n\n## Supported Versions\n\n| Version | Supported |\n|---------| ------------------ |\n| 6.0.x | :white_check_mark: |\n| 5.14.x | :white_check_mark: |\n| < 5.14 | :x: |\n\n## Reporting a Vulnerability\n\nTo report a security vulnerability, you have two options:\n\n- [Privately report a vulnerability](https://github.com/junit-team/junit-framework/security/advisories/new) on GitHub (see [docs](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability) for details)\n- Send an email to security@junit.org. You can use the [published OpenPGP key](https://keys.openpgp.org/search?q=security%40junit.org) with fingerprint `0152DA30EABC7ABADCB09D10D9A6B1329D191D25` to encrypt the message body.\n"
},
{
"path": "build.gradle.kts",
"content": "import junitbuild.extensions.dependencyProject\n\nplugins {\n\tid(\"junitbuild.base-conventions\")\n\tid(\"junitbuild.build-metadata\")\n\tid(\"junitbuild.checkstyle-nohttp\")\n\tid(\"junitbuild.jacoco-aggregation-conventions\")\n\tid(\"junitbuild.temp-maven-repo\")\n}\n\ndescription = \"JUnit\"\ngroup = \"org.junit\"\n\nval license by extra(License(\n\tname = \"Eclipse Public License v2.0\",\n\turl = uri(\"https://www.eclipse.org/legal/epl-v20.html\"),\n\theaderFile = layout.projectDirectory.file(\"gradle/config/spotless/eclipse-public-license-2.0.java\")\n))\n\nval platformProjects by extra(listOf(\n\t\tprojects.junitPlatformCommons,\n\t\tprojects.junitPlatformConsole,\n\t\tprojects.junitPlatformConsoleStandalone,\n\t\tprojects.junitPlatformEngine,\n\t\tprojects.junitPlatformLauncher,\n\t\tprojects.junitPlatformReporting,\n\t\tprojects.junitPlatformSuite,\n\t\tprojects.junitPlatformSuiteApi,\n\t\tprojects.junitPlatformSuiteEngine,\n\t\tprojects.junitPlatformTestkit\n).map { dependencyProject(it) })\n\nval jupiterProjects by extra(listOf(\n\t\tprojects.junitJupiter,\n\t\tprojects.junitJupiterApi,\n\t\tprojects.junitJupiterEngine,\n\t\tprojects.junitJupiterMigrationsupport,\n\t\tprojects.junitJupiterParams\n).map { dependencyProject(it) })\n\nval vintageProjects by extra(listOf(\n\tdependencyProject(projects.junitVintageEngine)\n))\n\nval mavenizedProjects by extra(listOf(dependencyProject(projects.junitStart)) + platformProjects + jupiterProjects + vintageProjects)\nval modularProjects by extra(mavenizedProjects - setOf(dependencyProject(projects.junitPlatformConsoleStandalone)))\n\ndependencies {\n\tmodularProjects.forEach {\n\t\tjacocoAggregation(it)\n\t}\n\tjacocoAggregation(projects.documentation)\n\tjacocoAggregation(projects.jupiterTests)\n\tjacocoAggregation(projects.platformTests)\n}\n"
},
{
"path": "documentation/.tool-versions",
"content": "nodejs 24.15.0\n"
},
{
"path": "documentation/README.md",
"content": "# JUnit User Guide\n\nThis subproject contains the Antora/AsciiDoc sources for the JUnit User Guide.\n\n## Structure\n\n- `modules/ROOT/pages`: AsciiDoc files\n- `src/test/java`: Java test source code that can be included in the AsciiDoc files\n- `src/test/kotlin`: Kotlin test source code that can be included in the AsciiDoc files\n- `src/test/resources`: Classpath resources that can be included in the AsciiDoc files or\n used in tests\n\n## Usage\n\n### Generate Antora site\n\nThis following Gradle command generates the HTML version of the User Guide as\n`build/antora/build/site`.\n\n```\n./gradlew antora\n```\n\nOn Linux operating systems, the `graphviz` package providing `/usr/bin/dot` must be\ninstalled in order to generate the PlantUML images used in the User Guide.\n"
},
{
"path": "documentation/antora-playbook.yml",
"content": "antora:\n extensions:\n - '@antora/collector-extension'\n - require: '@antora/lunr-extension'\n index_latest_only: true\n index_by_heading: true\n - require: '@springio/antora-extensions/root-component-extension'\n root_component_name: junit\n - require: '@springio/antora-extensions/root-attachments-extension'\n - require: '@springio/antora-xref-extension'\nsite:\n title: JUnit User Guide\n start_page: junit::overview.adoc\ncontent:\n sources:\n - url: @GIT_REPO_ROOT@\n branches: @GIT_BRANCH_NAME@\n start_path: documentation\n worktrees: true\nasciidoc:\n extensions:\n - '@asciidoctor/tabs'\n attributes:\n page-pagination: ''\n idprefix: '@'\n idseparator: '-@'\n table-caption: false\n table-frame: 'none@'\n table-grid: 'rows@'\n table-stripes: 'odd@'\n figure-caption: false\n example-caption: false\n listing-caption: false\n hide-uri-scheme: '@'\n attribute-missing: warn\n tabs-sync-option: ''\nruntime:\n log:\n failure_level: warn\nui:\n bundle:\n url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable\n snapshot: true\n supplemental_files:\n - path: css/vendor/tabs.css\n contents: @GIT_REPO_ROOT@/documentation/node_modules/@asciidoctor/tabs/dist/css/tabs.css\n - path: js/vendor/tabs.js\n contents: @GIT_REPO_ROOT@/documentation/node_modules/@asciidoctor/tabs/dist/js/tabs.js\n - path: partials/footer-scripts.hbs\n contents: |\n \n \n \n {{#if env.SITE_SEARCH_PROVIDER}}\n {{> search-scripts}}\n {{/if}}\n - path: partials/head-styles.hbs\n contents: |\n by rootProject\nval modularProjects: List by rootProject\n\n// Because we need to set up Javadoc aggregation\nmodularProjects.forEach { evaluationDependsOn(it.path) }\n\njavaLibrary {\n\tmainJavaVersion = JavaVersion.VERSION_17\n\ttestJavaVersion = JavaVersion.VERSION_17\n}\n\nval apiReport = configurations.dependencyScope(\"apiReport\")\nval apiReportClasspath = configurations.resolvable(\"apiReportClasspath\") {\n\textendsFrom(apiReport.get())\n}\nval standaloneConsoleLauncher = configurations.dependencyScope(\"standaloneConsoleLauncher\")\nval standaloneConsoleLauncherClasspath = configurations.resolvable(\"standaloneConsoleLauncherClasspath\") {\n\textendsFrom(standaloneConsoleLauncher.get())\n}\nval attestation = configurations.dependencyScope(\"attestation\")\nval attestationClasspath = configurations.resolvable(\"attestationClasspath\") {\n\textendsFrom(attestation.get())\n\tisTransitive = false\n}\nval allJavadocSinceValues = configurations.dependencyScope(\"allJavadocSinceValues\")\nval allJavadocSinceValuesClasspath = configurations.resolvable(\"allJavadocSinceValuesClasspath\") {\n\textendsFrom(allJavadocSinceValues.get())\n\tattributes {\n\t\tattribute(LibraryElements.LIBRARY_ELEMENTS_ATTRIBUTE, named(\"javadoc-since-values\"))\n\t}\n}\nval tools by sourceSets.creating\nval toolsImplementation by configurations.getting\n\ndependencies {\n\timplementation(projects.junitJupiterApi) {\n\t\tbecause(\"Jupiter API is used in src/main/java\")\n\t}\n\n\tcompileOnlyApi(libs.jspecify)\n\n\t// Pull in all \"modular projects\" to ensure that they are included\n\t// in reports generated by the ApiReportGenerator.\n\tmodularProjects.forEach { apiReport(it) }\n\tapiReport(libs.openTestReporting.tooling.spi)\n\n\tmodularProjects.forEach { allJavadocSinceValues(it) }\n\n\t// Pull in all \"mavenized projects\" to ensure that they are included\n\t// in the generation of build provenance attestation.\n\tmavenizedProjects.forEach { attestation(it) }\n\n\ttestImplementation(projects.junitJupiterMigrationsupport)\n\ttestImplementation(projects.junitPlatformConsole)\n\ttestImplementation(projects.junitPlatformSuite)\n\ttestImplementation(projects.junitPlatformTestkit)\n\ttestImplementation(projects.junitVintageEngine)\n\ttestImplementation(kotlin(\"stdlib\"))\n\ttestImplementation(libs.kotlinx.coroutines.test)\n\ttestRuntimeOnly(kotlin(\"reflect\"))\n\n\ttoolsImplementation(projects.junitPlatformCommons)\n\ttoolsImplementation(libs.classgraph)\n\ttoolsImplementation(libs.apiguardian)\n\n\ttestImplementation(libs.jimfs) {\n\t\tbecause(\"Jimfs is used in src/test/java\")\n\t}\n\n\tstandaloneConsoleLauncher(projects.junitPlatformConsoleStandalone)\n}\n\nval buildRevision: String by rootProject.extra\nval snapshot = version.isSnapshot()\nval releaseBranch = if (snapshot) \"HEAD\" else \"r${version}\"\nval replaceCurrentDocs = buildParameters.documentation.replaceCurrentDocs\nval ota4jDocVersion = libs.versions.opentest4j.map { if (it.isSnapshot()) \"snapshot\" else it }.get()\nval apiGuardianDocVersion = libs.versions.apiguardian.map { if (it.isSnapshot()) \"snapshot\" else it }.get()\n\nval generatedAsciiDocPath = layout.buildDirectory.dir(\"generated/asciidoc\")\nval consoleLauncherOptionsFile = generatedAsciiDocPath.map { it.file(\"console-launcher-options.txt\") }\nval consoleLauncherDiscoverOptionsFile = generatedAsciiDocPath.map { it.file(\"console-launcher-discover-options.txt\") }\nval consoleLauncherExecuteOptionsFile = generatedAsciiDocPath.map { it.file(\"console-launcher-execute-options.txt\") }\nval consoleLauncherEnginesOptionsFile = generatedAsciiDocPath.map { it.file(\"console-launcher-engines-options.txt\") }\nval experimentalApisTableFile = generatedAsciiDocPath.map { it.file(\"experimental-apis-table.adoc\") }\nval deprecatedApisTableFile = generatedAsciiDocPath.map { it.file(\"deprecated-apis-table.adoc\") }\nval standaloneConsoleLauncherShadowedArtifactsFile = generatedAsciiDocPath.map { it.file(\"console-launcher-standalone-shadowed-artifacts.adoc\") }\n\nval jdkJavadocBaseUrl = \"https://docs.oracle.com/en/java/javase/${JavaVersion.current().majorVersion}/docs/api\"\nval elementListsDir = layout.buildDirectory.dir(\"elementLists\")\nval externalModulesWithoutModularJavadoc = mapOf(\n\t\t\"org.apiguardian.api\" to \"https://apiguardian-team.github.io/apiguardian/docs/$apiGuardianDocVersion/api/\",\n\t\t\"org.assertj.core\" to \"https://javadoc.io/doc/org.assertj/assertj-core/${libs.versions.assertj.get()}/\",\n\t\t\"org.opentest4j\" to \"https://ota4j-team.github.io/opentest4j/docs/$ota4jDocVersion/api/\",\n\t\t\"org.jspecify\" to \"https://jspecify.dev/docs/api/\",\n)\nrequire(externalModulesWithoutModularJavadoc.values.all { it.endsWith(\"/\") }) {\n\t\"all base URLs must end with a trailing slash: $externalModulesWithoutModularJavadoc\"\n}\n\ntasks {\n\n\tval consoleLauncherTestReportsDir = project.layout.buildDirectory.dir(\"console-launcher-test-results\")\n\tval consoleLauncherTestEventXmlFiles =\n\t\tfiles(consoleLauncherTestReportsDir.map { it.asFileTree.matching { include(\"**/open-test-report.xml\") } })\n\n\tval consoleLauncherTest by registering(RunConsoleLauncher::class) {\n\t\targs.addAll(\"execute\")\n\t\targs.addAll(\"--scan-classpath\")\n\t\targs.addAll(\"--config=junit.platform.reporting.open.xml.enabled=true\")\n\t\targs.addAll(\"--config=junit.platform.reporting.open.xml.git.enabled=true\")\n\t\targs.addAll(\"--config=junit.platform.output.capture.stdout=true\")\n\t\targs.addAll(\"--config=junit.platform.output.capture.stderr=true\")\n\t\targs.addAll(\"--config=junit.platform.discovery.issue.severity.critical=warning\")\n\t\toutputs.dir(consoleLauncherTestReportsDir)\n\t\targumentProviders.add(CommandLineArgumentProvider {\n\t\t\tlistOf(\n\t\t\t\t\"--reports-dir=${consoleLauncherTestReportsDir.get()}\",\n\t\t\t)\n\t\t})\n\t\targs.addAll(\"--include-classname\", \".*Tests\")\n\t\targs.addAll(\"--include-classname\", \".*Demo\")\n\t\targs.addAll(\"--exclude-tag\", \"exclude\")\n\t\targs.addAll(\"--exclude-tag\", \"timeout\")\n\n\t\tdoFirst {\n\t\t\tconsoleLauncherTestReportsDir.get().asFile.deleteRecursively()\n\t\t}\n\n\t\tfinalizedBy(generateOpenTestHtmlReport)\n\t}\n\n\tgenerateOpenTestHtmlReport {\n\t\tmustRunAfter(consoleLauncherTest)\n\t\tinputs.files(consoleLauncherTestEventXmlFiles).withPathSensitivity(RELATIVE).skipWhenEmpty()\n\t\targumentProviders += CommandLineArgumentProvider {\n\t\t\tconsoleLauncherTestEventXmlFiles.files.map { it.absolutePath }.toList()\n\t\t}\n\t}\n\n\tregister(\"consoleLauncher\") {\n\t\thideOutput = false\n\t\toutputs.upToDateWhen { false }\n\t}\n\n\ttest {\n\t\tinclude(\"**/*Demo.class\")\n\t\t(options as JUnitPlatformOptions).apply {\n\t\t\tincludeEngines(\"junit-vintage\")\n\t\t\tincludeTags(\"timeout\")\n\t\t\tsystemProperty(\"junit.platform.discovery.issue.severity.critical\", \"warning\")\n\t\t}\n\t}\n\n\tcheck {\n\t\tdependsOn(consoleLauncherTest)\n\t}\n\n\tnamed(tools.compileJavaTaskName) {\n\t\toptions.release.set(25)\n\t}\n\n\tnamed(\"checkstyleTools\") {\n\t\tconfig = resources.text.fromFile(checkstyle.configDirectory.file(\"checkstyleMain.xml\"))\n\t}\n\n\tval generateConsoleLauncherOptions by registering(CaptureJavaExecOutput::class) {\n\t\tclasspath.from(standaloneConsoleLauncherClasspath)\n\t\tmainClass = \"org.junit.platform.console.ConsoleLauncher\"\n\t\targs.addAll(\"--help\", \"--disable-banner\")\n\t\toutputFile = consoleLauncherOptionsFile\n\t}\n\n\tval generateConsoleLauncherDiscoverOptions by registering(CaptureJavaExecOutput::class) {\n\t\tclasspath.from(standaloneConsoleLauncherClasspath)\n\t\tmainClass = \"org.junit.platform.console.ConsoleLauncher\"\n\t\targs.addAll(\"discover\", \"--help\", \"--disable-banner\")\n\t\toutputFile = consoleLauncherDiscoverOptionsFile\n\t}\n\n\tval generateConsoleLauncherExecuteOptions by registering(CaptureJavaExecOutput::class) {\n\t\tclasspath.from(standaloneConsoleLauncherClasspath)\n\t\tmainClass = \"org.junit.platform.console.ConsoleLauncher\"\n\t\targs.addAll(\"execute\", \"--help\", \"--disable-banner\")\n\t\toutputFile = consoleLauncherExecuteOptionsFile\n\t}\n\n\tval generateConsoleLauncherEnginesOptions by registering(CaptureJavaExecOutput::class) {\n\t\tclasspath.from(standaloneConsoleLauncherClasspath)\n\t\tmainClass = \"org.junit.platform.console.ConsoleLauncher\"\n\t\targs.addAll(\"engines\", \"--help\", \"--disable-banner\")\n\t\toutputFile = consoleLauncherEnginesOptionsFile\n\t}\n\n\tval generateApiTables by registering(JavaExec::class) {\n\t\tclasspath = tools.runtimeClasspath\n\t\tmainClass = \"org.junit.api.tools.ApiReportGenerator\"\n\t\tsystemProperty(\"api.moduleNames\", modularProjects.map { it.javaModuleName }.sorted().joinToString(\",\"))\n\t\tjvmArgumentProviders += ClasspathSystemPropertyProvider(\"api.modulePath\", apiReportClasspath.get())\n\t\targumentProviders += CommandLineArgumentProvider {\n\t\t\tlistOf(\n\t\t\t\t\"DEPRECATED=${deprecatedApisTableFile.get().asFile.absolutePath}\",\n\t\t\t\t\"EXPERIMENTAL=${experimentalApisTableFile.get().asFile.absolutePath}\",\n\t\t\t)\n\t\t}\n\t\toutputs.cacheIf { true }\n\t\toutputs.file(deprecatedApisTableFile)\n\t\toutputs.file(experimentalApisTableFile)\n\t}\n\n\tval generateStandaloneConsoleLauncherShadowedArtifactsFile by registering(GenerateStandaloneConsoleLauncherShadowedArtifactsFile::class) {\n\t\tinputJar.fileProvider(standaloneConsoleLauncherClasspath.flatMap { it.elements.map { it.single().asFile } })\n\t\toutputFile = standaloneConsoleLauncherShadowedArtifactsFile\n\t}\n\n\tplantUml {\n\t\tfileFormat = \"SVG\"\n\t\toutputs.cacheIf { true }\n\t}\n\n\tval plantUmlOutputDirectory = plantUml.flatMap { it.outputDirectory }\n\n\tval generateAsciidocInputs by registering {\n\t\tdependsOn(\n\t\t\tgenerateConsoleLauncherOptions,\n\t\t\tgenerateConsoleLauncherDiscoverOptions,\n\t\t\tgenerateConsoleLauncherExecuteOptions,\n\t\t\tgenerateConsoleLauncherEnginesOptions,\n\t\t\tgenerateApiTables,\n\t\t\tgenerateStandaloneConsoleLauncherShadowedArtifactsFile,\n\t\t\tplantUmlOutputDirectory\n\t\t)\n\t}\n\n\tval downloadJavadocElementLists by registering {\n\t\toutputs.cacheIf { true }\n\t\toutputs.dir(elementListsDir).withPropertyName(\"elementListsDir\")\n\t\tinputs.property(\"externalModulesWithoutModularJavadoc\", externalModulesWithoutModularJavadoc)\n\t\tdoFirst {\n\t\t\texternalModulesWithoutModularJavadoc.forEach { (moduleName, baseUrl) ->\n\t\t\t\tval resource = resources.text.fromUri(\"${baseUrl}element-list\")\n\t\t\t\telementListsDir.get().asFile.resolve(moduleName).apply {\n\t\t\t\t\tmkdir()\n\t\t\t\t\tresolve(\"element-list\").writeText(\"module:$moduleName\\n${resource.asString()}\")\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\tval mergeJavadocSinceValues by registering {\n\t\tinputs.files(allJavadocSinceValuesClasspath).withPathSensitivity(PathSensitivity.NONE)\n\t\tval outputFile = layout.buildDirectory.file(\"docs/aggregated-javadoc-since-values.txt\")\n\t\toutputs.file(outputFile)\n\t\toutputs.cacheIf { true }\n\t\tdoFirst {\n\t\t\tval initialVersions = setOf(\"1.0\", \"4.12\", \"5.0\")\n\t\t\tval noPublicItems = setOf(\"1.3.1\", \"5.0.3\", \"5.4.1\", \"5.11.3\")\n\t\t\tval excludes = initialVersions + noPublicItems\n\t\t\tval values = allJavadocSinceValuesClasspath.get().files.asSequence()\n\t\t\t\t.flatMap { it.readLines().asSequence() }\n\t\t\t\t.filter { it.isNotBlank() && it !in excludes }\n\t\t\t\t.sortedBy { VersionNumber(it) }\n\t\t\t\t.distinct()\n\t\t\twith(outputFile.get().asFile.toPath()) {\n\t\t\t\tFiles.createDirectories(parent)\n\t\t\t\twriteLines(values)\n\t\t\t}\n\t\t}\n\t}\n\n\tval aggregateJavadocs by registering(Javadoc::class) {\n\t\tdependsOn(modularProjects.map { it.tasks.jar })\n\t\tdependsOn(downloadJavadocElementLists)\n\t\tgroup = \"Documentation\"\n\t\tdescription = \"Generates aggregated Javadocs\"\n\n\t\ttitle = \"JUnit $version API\"\n\n\t\tval additionalStylesheetFile = \"src/javadoc/junit-stylesheet.css\"\n\t\tinputs.file(additionalStylesheetFile)\n\t\tval overviewFile = \"src/javadoc/junit-overview.html\"\n\t\tinputs.file(overviewFile)\n\n\t\toptions {\n\n\t\t\tmemberLevel = JavadocMemberLevel.PROTECTED\n\t\t\theader = rootProject.description\n\t\t\tencoding = \"UTF-8\"\n\t\t\tlocale = \"en\"\n\t\t\toverview = overviewFile\n\t\t\tjFlags(\"-Xmx1g\")\n\n\t\t\tthis as StandardJavadocDocletOptions\n\t\t\tsplitIndex(true)\n\t\t\taddBooleanOption(\"Xdoclint:all,-missing\", true)\n\t\t\taddBooleanOption(\"Werror\", true)\n\t\t\taddBooleanOption(\"html5\", true)\n\t\t\taddMultilineStringsOption(\"tag\").value = listOf(\n\t\t\t\t\t\"apiNote:a:API Note:\",\n\t\t\t\t\t\"implNote:a:Implementation Note:\"\n\t\t\t)\n\n\t\t\tlinks(jdkJavadocBaseUrl)\n\t\t\tlinks(\"https://junit.org/junit4/javadoc/${libs.versions.junit4.get()}/\")\n\t\t\texternalModulesWithoutModularJavadoc.forEach { (moduleName, baseUrl) ->\n\t\t\t\tlinksOffline(baseUrl, elementListsDir.get().asFile.resolve(moduleName).absolutePath)\n\t\t\t}\n\n\t\t\tgroups = mapOf(\n\t\t\t\t\t\"Jupiter\" to listOf(\"org.junit.jupiter*\"),\n\t\t\t\t\t\"Vintage\" to listOf(\"org.junit.vintage*\"),\n\t\t\t\t\t\"Platform\" to listOf(\"org.junit.platform*\")\n\t\t\t)\n\t\t\taddStringOption(\"-add-stylesheet\", additionalStylesheetFile)\n\t\t\taddBooleanOption(\"-no-fonts\", true)\n\t\t\tuse(true)\n\t\t\tnoTimestamp(true)\n\n\t\t\taddStringsOption(\"-module\", \",\").value = modularProjects.map { it.javaModuleName }\n\t\t\taddOption(ModuleSpecificJavadocFileOption(\"-module-source-path\", modularProjects.associate { project ->\n\t\t\t\tproject.javaModuleName to provider {\n\t\t\t\t\tfiles(\n\t\t\t\t\t\tproject.sourceSets.named { it.startsWith(\"main\") }.map {\n\t\t\t\t\t\t\tit.allJava.srcDirs.filter { it.exists() }\n\t\t\t\t\t\t}\n\t\t\t\t\t).asPath\n\t\t\t\t}\n\t\t\t}))\n\t\t\taddStringOption(\"-add-modules\", \"info.picocli,org.opentest4j.reporting.events,de.siegmar.fastcsv\")\n\t\t\taddOption(ModuleSpecificJavadocFileOption(\"-add-reads\", mapOf(\n\t\t\t\t\t\"org.junit.platform.console\" to provider { \"info.picocli\" },\n\t\t\t\t\t\"org.junit.platform.reporting\" to provider { \"org.opentest4j.reporting.events\" },\n\t\t\t\t\t\"org.junit.jupiter.params\" to provider { \"de.siegmar.fastcsv\" }\n\t\t\t)))\n\n\t\t\tval javadocSinceValuesFile: Provider = mergeJavadocSinceValues.map { it.outputs.files.singleFile }\n\t\t\tinputs.file(javadocSinceValuesFile)\n\t\t\t\t.withPathSensitivity(PathSensitivity.NONE)\n\t\t\t\t.withPropertyName(\"javadoc-since-values-file\")\n\t\t\taddOption(JavadocValuesOption(\"-since\", javadocSinceValuesFile.map { file ->\n\t\t\t\tfile.readLines().asSequence().filter { it.isNotBlank() }.toList()\n\t\t\t}))\n\t\t}\n\n\t\tsource(modularProjects.map { project ->\n\t\t\tfiles(project.sourceSets.named { it.startsWith(\"main\") }.map { it.allJava })\n\t\t})\n\t\tclasspath = files(modularProjects.map { it.sourceSets.main.get().compileClasspath })\n\n\t\tsetMaxMemory(\"1024m\")\n\t\toptions.destinationDirectory = layout.buildDirectory.dir(\"docs/javadoc\").get().asFile\n\t}\n\n\tval fixJavadoc by registering(Copy::class) {\n\t\tdependsOn(aggregateJavadocs)\n\t\tgroup = \"Documentation\"\n\t\tdescription = \"Fix links to external API specs in the locally aggregated Javadoc HTML files\"\n\n\t\tval inputDir = aggregateJavadocs.map { it.destinationDir!! }\n\t\tinputs.property(\"externalModulesWithoutModularJavadoc\", externalModulesWithoutModularJavadoc)\n\t\tfrom(inputDir.map { File(it, \"element-list\") }) {\n\t\t\t// For compatibility with pre JDK 10 versions of the Javadoc tool\n\t\t\trename { \"package-list\" }\n\t\t}\n\t\tfrom(inputDir) {\n\t\t\tfilesMatching(\"**/*.html\") {\n\t\t\t\tval favicon =\n\t\t\t\t\t\"\"\"\n\t\t\t\t\t\t> or the implementation of\nthird-party test engines listed in the\nhttps://github.com/junit-team/junit-framework/wiki/Third-party-Extensions#junit-platform-test-engines[JUnit wiki].\nYou will also find various tutorials and blogs on the Internet that demonstrate how to\nwrite a custom `TestEngine`.\n\nNOTE: `{HierarchicalTestEngine}` is a convenient abstract base implementation of the\n`TestEngine` SPI (used by the `{junit-jupiter-engine}`) that only requires implementors to\nprovide the logic for test discovery. It implements execution of `TestDescriptors` that\nimplement the `Node` interface, including support for parallel execution.\n\n[[registration]]\n== Registering a TestEngine\n\n`TestEngine` registration is supported via Java's `{ServiceLoader}` mechanism.\n\nFor example, the `junit-jupiter-engine` module registers its\n`org.junit.jupiter.engine.JupiterTestEngine` in a file named\n`org.junit.platform.engine.TestEngine` within the `/META-INF/services` folder in the\n`junit-jupiter-engine` JAR.\n\n[[requirements]]\n== Requirements\n\nNOTE: The words \"must\", \"must not\", \"required\", \"shall\", \"shall not\", \"should\", \"should\nnot\", \"recommended\", \"may\", and \"optional\" in this section are to be interpreted as\ndescribed in https://www.ietf.org/rfc/rfc2119.txt[RFC 2119.]\n\n[[requirements-mandatory]]\n=== Mandatory requirements\n\nFor interoperability with build tools and IDEs, `TestEngine` implementations must adhere\nto the following requirements:\n\n* The `TestDescriptor` returned from `TestEngine.discover()` _must_ be the root of a tree\n of `TestDescriptor` instances. This implies that there _must not_ be any cycles between\n a node and its descendants.\n* The hierarchy of test descriptors returned from `TestEngine.discover()` _must_ be\n mutable, but the test descriptors _must_ otherwise be immutable after discovery.\n* A `TestEngine` _must_ be able to discover `UniqueIdSelectors` for any unique ID that it\n previously generated and returned from `TestEngine.discover()`. This enables selecting a\n subset of tests to execute or rerun.\n* The `executionSkipped`, `executionStarted`, and `executionFinished` methods of the\n `EngineExecutionListener` passed to `TestEngine.execute()` _must_ be called for every\n `TestDescriptor` node in the tree returned from `TestEngine.discover()` at most\n once. Parent nodes _must_ be reported as started before their children and as finished\n after their children. If a node is reported as skipped, there _must not_ be any events\n reported for its descendants.\n\n[[requirements-enhanced-compatibility]]\n=== Enhanced compatibility\n\nAdhering to the following requirements is optional but recommended for enhanced\ncompatibility with build tools and IDEs:\n\n* Unless to indicate an empty discovery result, the `TestDescriptor` returned from\n `TestEngine.discover()` _should_ have children rather than being completely dynamic.\n This allows tools to display the structure of the tests and to select a subset of tests\n to execute.\n* When resolving `UniqueIdSelectors`, a `TestEngine` _should_ only return `TestDescriptor`\n instances with matching unique IDs including their ancestors but _may_ return additional\n siblings or other nodes that are required for the execution of the selected tests.\n* `TestEngines` _should_ support xref:running-tests/tags.adoc[tagging] tests and containers so\n that tag filters can be applied when discovering tests.\n* [[requirements-cancellation]] A `TestEngine` _should_ cancel its execution\n when the `{CancellationToken}` it is passed as part of the `ExecutionRequest` indicates\n that cancellation has been requested. In this case, it _should_ report any remaining\n `TestDescriptors` as skipped but not report any events for their descendants. It _may_\n report already started `TestDescriptors` as aborted in case they have not been executed\n completely. If a `TestEngine` supports cancellation, it should clean up any resources\n that it has created just like if execution had finished regularly.\n\n[[discovery-issues]]\n== Reporting Discovery Issues\n\nTest engines should report xref:running-tests/discovery-issues.adoc[discovery issues] if they\nencounter any problems or potential misconfigurations during test discovery. This is\nespecially important if the issue could lead to tests not being executed at all or only\npartially.\n\nIn order to report a `{DiscoveryIssue}`, a test engine should call the\n`issueEncountered()` method on the `{EngineDiscoveryListener}` available via the\n`{EngineDiscoveryRequest}` passed to its `discover()` method. Rather than passing the\nlistener around, the `{DiscoveryIssueReporter}` interface should be used. It also provides\na way to create a `Condition` that reports a discovery issue if its check fails and may\nbe used as a `Predicate` or `Consumer`. Please refer to the implementations of the\n<> for examples.\n\nMoreover, xref:advanced-topics/testkit.adoc#engine-discovery[Engine Test Kit] provides a way to write tests for\nreported discovery issues.\n"
},
{
"path": "documentation/modules/ROOT/pages/advanced-topics/junit-platform-reporting.adoc",
"content": "= JUnit Platform Reporting\n\nThe `junit-platform-reporting` artifact contains `{TestExecutionListener}` implementations\nthat generate XML test reports in two flavors:\n<> and\n<>.\n\nNOTE: The module also contains other `TestExecutionListener` implementations that can be\nused to build custom reporting. See xref:running-tests/using-listeners-and-interceptors.adoc[] for details.\n\n[[output-directory]]\n== Output Directory\n\nThe JUnit Platform provides an `{OutputDirectoryCreator}` via `{EngineDiscoveryRequest}`\nand `{TestPlan}` to registered xref:advanced-topics/engines.adoc[test engines] and\nxref:running-tests/using-listeners-and-interceptors.adoc[listeners], respectively. Its root directory can be configured\nvia the following xref:running-tests/configuration-parameters.adoc[configuration parameter]:\n\n`junit.platform.reporting.output.dir=`::\n Configure the output directory for reporting. By default, `build` is used if a Gradle\n build script is found, and `target` if a Maven POM is found; otherwise, the current\n working directory is used.\n\nTo create a unique output directory per test run, you can use the `\\{uniqueNumber}`\nplaceholder in the path. For example, `reports/junit-\\{uniqueNumber}` will create\ndirectories like `reports/junit-8803697269315188212`. This can be useful when using\nGradle's or Maven's parallel execution capabilities which create multiple JVM forks\nthat run concurrently.\n\n[[open-test-reporting]]\n== Open Test Reporting\n\n`{OpenTestReportGeneratingListener}` writes an XML report for the entire execution in the\nevent-based format specified by {OpenTestReporting} which supports all features of the\nJUnit Platform such as hierarchical test structures, display names, tags, etc.\n\nThe listener is auto-registered and can be configured via the following\nxref:running-tests/configuration-parameters.adoc[configuration parameters]:\n\n`junit.platform.reporting.open.xml.enabled=true|false`::\n Enable/disable writing the report; defaults to `false`.\n`junit.platform.reporting.open.xml.git.enabled=true|false`::\n Enable/disable including information about the Git repository (see https://github.com/ota4j-team/open-test-reporting#git[Git extension schema] of open-test-reporting); defaults to `false`.\n`junit.platform.reporting.open.xml.socket=`::\n Optional port number to redirect events to a socket instead of a file. When specified, the\n listener will connect to `127.0.0.1:` and send the XML events to the socket. The socket\n connection is automatically closed when the test execution completes.\n\nIf enabled, the listener creates an XML report file named `open-test-report.xml` in the\nconfigured <>, unless the\n`junit.platform.reporting.open.xml.socket` configuration parameter is set, in which case the\nevents are sent to the specified socket instead.\n\nIf xref:running-tests/capturing-standard-output-error.adoc[output capturing] is enabled, the captured output\nwritten to `System.out` and `System.err` will be included in the report as well.\n\nTIP: The {OpenTestReportingCliTool} can be used to convert from the event-based format to\nthe hierarchical format which is more human-readable.\n\n=== Gradle\n\nFor Gradle, writing Open Test Reporting compatible XML reports can be enabled and\nconfigured via system properties. The following samples configure its output directory to\nbe the same directory Gradle uses for its own XML reports. A `CommandLineArgumentProvider`\nis used to keep the tasks relocatable across different machines which is important when\nusing Gradle's Build Cache.\n\n[source,groovy,indent=0]\n[subs=attributes+]\n.Groovy DSL\n----\ndependencies {\n testRuntimeOnly(\"org.junit.platform:junit-platform-reporting:{version}\")\n}\ntasks.withType(Test).configureEach {\n def outputDir = reports.junitXml.outputLocation\n jvmArgumentProviders << ({\n [\n \"-Djunit.platform.reporting.open.xml.enabled=true\",\n \"-Djunit.platform.reporting.output.dir=${outputDir.get().asFile.absolutePath}\"\n ]\n } as CommandLineArgumentProvider)\n}\n----\n\n[source,kotlin,indent=0]\n[subs=attributes+]\n.Kotlin DSL\n----\ndependencies {\n testRuntimeOnly(\"org.junit.platform:junit-platform-reporting:{version}\")\n}\ntasks.withType().configureEach {\n val outputDir = reports.junitXml.outputLocation\n jvmArgumentProviders += CommandLineArgumentProvider {\n\t\tlistOf(\n\t\t\t\"-Djunit.platform.reporting.open.xml.enabled=true\",\n\t\t\t\"-Djunit.platform.reporting.output.dir=${outputDir.get().asFile.absolutePath}\"\n\t\t)\n\t}\n}\n----\n\n=== Maven\n\nFor Maven Surefire/Failsafe, you can enable Open Test Reporting output and configure the\nresulting XML files to be written to the same directory Surefire/Failsafe uses for its own\nXML reports as follows:\n\n[source,xml,indent=0]\n[subs=attributes+]\n----\n\n\t\n\t\n\t\t\n\t\t\torg.junit.platform \n\t\t\tjunit-platform-reporting \n\t\t\t{version} \n\t\t\ttest \n\t\t \n\t \n\t\n\t\t\n\t\t\t\n\t\t\t\tmaven-surefire-plugin \n\t\t\t\t{surefire-version} \n\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\tjunit.platform.reporting.open.xml.enabled = true\n\t\t\t\t\t\t\tjunit.platform.reporting.output.dir = target/surefire-reports\n\t\t\t\t\t\t \n\t\t\t\t\t \n\t\t\t\t \n\t\t\t \n\t\t \n\t \n\t\n \n----\n\n=== Console Launcher\n\nWhen using the xref:running-tests/console-launcher.adoc[], you can enable Open Test Reporting\noutput by setting the configuration parameters via `--config`:\n\n[source,console,subs=attributes+]\n----\n$ java -jar junit-platform-console-standalone-{version}.jar \\\n --config=junit.platform.reporting.open.xml.enabled=true \\\n --config=junit.platform.reporting.output.dir=reports\n----\n\nConfiguration parameters can also be set in a custom properties file supplied as a\nclasspath resource via the `--config-resource` option:\n\n[source,console,subs=attributes+]\n----\n$ java -jar junit-platform-console-standalone-{version}.jar \\\n --config-resource=configuration.properties\n----\n\n[[legacy-xml]]\n== Legacy XML format\n\n`{LegacyXmlReportGeneratingListener}` generates a separate XML report for each root in the\n`{TestPlan}`. Note that the generated XML format is compatible with the de facto standard\nfor JUnit 4 based test reports that was made popular by the Ant build system.\n\nThe `LegacyXmlReportGeneratingListener` is used by the xref:running-tests/console-launcher.adoc[]\nas well.\n"
},
{
"path": "documentation/modules/ROOT/pages/advanced-topics/junit-platform-suite-engine.adoc",
"content": "= JUnit Platform Suite Engine\n\nThe Suite Engine supports the declarative selection and execution of tests from _any_ test\nengine on the JUnit Platform using the xref:advanced-topics/launcher-api.adoc[].\n\nimage::junit-platform-suite-engine-diagram.svg[role=text-center]\n\n[[setup]]\n== Setup\n\nIn addition to the `junit-platform-suite-api` and `junit-platform-suite-engine` artifacts,\nyou need _at least one_ other test engine and its dependencies on the classpath. See\nxref:appendix.adoc#dependency-metadata[Dependency Metadata] for details regarding group IDs, artifact IDs, and versions.\n\n[[setup-required-dependencies]]\n=== Required Dependencies\n\n* `junit-platform-suite-api` in _test_ scope: artifact containing annotations needed to\n configure a test suite\n* `junit-platform-suite-engine` in _test runtime_ scope: implementation of the\n `TestEngine` API for declarative test suites\n\nNOTE: Both of the required dependencies are aggregated in the `junit-platform-suite`\nartifact which can be declared in _test_ scope instead of declaring explicit dependencies\non `junit-platform-suite-api` and `junit-platform-suite-engine`.\n\n[[setup-transitive-dependencies]]\n=== Transitive Dependencies\n\n* `junit-platform-launcher` in _test_ scope\n* `junit-platform-engine` in _test_ scope\n* `junit-platform-commons` in _test_ scope\n* `opentest4j` in _test_ scope\n\n[[example]]\n== @Suite Example\n\nAnnotate a class with `@Suite` to have it marked as a test suite on the JUnit Platform. As\nseen in the following example, selector and filter annotations can be used to control the\ncontents of the suite.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/SuiteDemo.java[tags=user_guide]\n----\n\n.Additional Configuration Options\nNOTE: There are numerous configuration options for discovering and filtering tests in a\ntest suite. Please consult the Javadoc of the `{suite-api-package}` package for a full\nlist of supported annotations and further details.\n\n== @BeforeSuite and @AfterSuite\n\n`@BeforeSuite` and `@AfterSuite` annotations can be used on methods inside a\n`@Suite`-annotated class. They will be executed before and after all tests of the test\nsuite, respectively.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/BeforeAndAfterSuiteDemo.java[tags=user_guide]\n----\n\n[[duplicate-test-execution]]\n== Duplicate Test Execution\n\nDepending on the declared selectors, different suites may contain the same tests,\npotentially with different configurations. Moreover, tests in a suite are executed in\naddition to the tests executed by every other test engine, which can result in the same\ntests being executed twice.\n\nimage::junit-platform-suite-engine-duplicate-test-execution-diagram.svg[role=text-center]\n\nTo prevent duplicate execution of tests within a suite, configure your build tool to\ninclude only the `junit-platform-suite` engine, or use a custom naming pattern. For\nexample, name all suites `*Suite` and all tests `*Test`, and configure your build tool to\ninclude only the former.\n\nAlternatively, consider xref:running-tests/tags.adoc[using tags] to select specific groups of\ntests.\n"
},
{
"path": "documentation/modules/ROOT/pages/advanced-topics/launcher-api.adoc",
"content": "= JUnit Platform Launcher API\n\nOne of the prominent goals of the JUnit Platform is to make the interface between JUnit\nand its programmatic clients – build tools and IDEs – more powerful and stable. The\npurpose is to decouple the internals of discovering and executing tests from all the\nfiltering and configuration that is necessary from the outside.\n\nJUnit Platform provides a `Launcher` API that can be used to discover, filter, and execute\ntests. Moreover, third party test libraries – like Spock or Cucumber – can plug into the\nJUnit Platform's launching infrastructure by providing a custom\nxref:advanced-topics/engines.adoc[TestEngine].\n\nimage::launcher-api-diagram.svg[role=text-center]\n\nThe launcher API is in the `{junit-platform-launcher}` module.\n\nAn example consumer of the launcher API is the `{ConsoleLauncher}` in the\n`{junit-platform-console}` project.\n\n[[discovery]]\n== Discovering Tests\n\nHaving _test discovery_ as a dedicated feature of the platform frees IDEs and build tools\nfrom most of the difficulties they had to go through to identify test classes and test\nmethods in previous versions of JUnit.\n\nUsage Example:\n\n[source,java,indent=0]\n----\ninclude::example$java/example/UsingTheLauncherForDiscoveryDemo.java[tags=imports]\n----\n\n[source,java,indent=0]\n----\ninclude::example$java/example/UsingTheLauncherForDiscoveryDemo.java[tags=discovery]\n----\n\nYou can select classes, methods, and all classes in a package or even search for all tests\nin the class-path or module-path. Discovery takes place across all participating test\nengines.\n\nThe resulting `TestPlan` is a hierarchical (and read-only) description of all engines,\nclasses, and test methods that fit the `LauncherDiscoveryRequest`. The client can\ntraverse the tree, retrieve details about a node, and get a link to the original source\n(like class, method, or file position). Every node in the test plan has a _unique ID_\nthat can be used to invoke a particular test or group of tests.\n\nClients can register one or more `{LauncherDiscoveryListener}` implementations via the\n`{LauncherDiscoveryRequestBuilder}` to gain insight into events that occur during test\ndiscovery. By default, the builder registers an \"abort on failure\" listener that aborts\ntest discovery after the first discovery failure is encountered. The default\n`LauncherDiscoveryListener` can be changed via the\n`junit.platform.discovery.listener.default` xref:running-tests/configuration-parameters.adoc[configuration\nparameter].\n\n[[execution]]\n== Executing Tests\n\nTo execute tests, clients can use the same `LauncherDiscoveryRequest` as in the discovery\nphase or create a new request. Test progress and reporting can be achieved by registering\none or more `{TestExecutionListener}` implementations with the `Launcher` as in the\nfollowing example.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/UsingTheLauncherDemo.java[tags=execution]\n----\n\nThere is no return value for the `execute()` method, but you can use a\n`TestExecutionListener` to aggregate the results. For examples see the\n`{SummaryGeneratingListener}`, `{LegacyXmlReportGeneratingListener}`, and\n`{UniqueIdTrackingListener}`.\n\nNOTE: All `TestExecutionListener` methods are called sequentially. Methods for start\nevents are called in registration order while methods for finish events are called in\nreverse order.\nTest case execution won't start before all `executionStarted` calls have returned.\n\n[[engines-custom]]\n== Registering a TestEngine\n\nSee the dedicated section on xref:advanced-topics/engines.adoc#registration[TestEngine registration] for\ndetails.\n\n[[post-discovery-filters-custom]]\n== Registering a PostDiscoveryFilter\n\nIn addition to specifying post-discovery filters as part of a `{LauncherDiscoveryRequest}`\npassed to the `{Launcher}` API, `{PostDiscoveryFilter}` implementations will be discovered\nat runtime via Java's `{ServiceLoader}` mechanism and automatically applied by the\n`Launcher` in addition to those that are part of the request.\n\nFor example, an `example.CustomTagFilter` class implementing `PostDiscoveryFilter` and\ndeclared within the `/META-INF/services/org.junit.platform.launcher.PostDiscoveryFilter`\nfile is loaded and applied automatically.\n\n[[launcher-session-listeners-custom]]\n== Registering a LauncherSessionListener\n\nRegistered implementations of `{LauncherSessionListener}` are notified when a\n`{LauncherSession}` is opened (before a `{Launcher}` first discovers and executes tests)\nand closed (when no more tests will be discovered or executed). They can be registered\nprogrammatically via the `{LauncherConfig}` that is passed to the `{LauncherFactory}`, or\nthey can be discovered at runtime via Java's `{ServiceLoader}` mechanism and automatically\nregistered with `LauncherSession` (unless automatic registration is disabled.)\n\n[[launcher-session-listeners-tool-support]]\n=== Tool Support\n\nThe following build tools and IDEs are known to provide full support for `LauncherSession`:\n\n* Gradle 4.6 and later\n* Maven Surefire/Failsafe 3.0.0-M6 and later\n* IntelliJ IDEA 2017.3 and later\n\nOther tools might also work but have not been tested explicitly.\n\n[[launcher-session-listeners-tool-example-usage]]\n=== Example Usage\n\nA `LauncherSessionListener` is well suited for implementing once-per-JVM setup/teardown\nbehavior since it's called before the first and after the last test in a launcher session,\nrespectively. The scope of a launcher session depends on the used IDE or build tool but\nusually corresponds to the lifecycle of the test JVM. A custom listener that starts an\nHTTP server before executing the first test and stops it after the last test has been\nexecuted, could look like this:\n\n[source,java]\n.src/test/java/example/session/GlobalSetupTeardownListener.java\n----\npackage example.session;\n\ninclude::example$java/example/session/GlobalSetupTeardownListener.java[tags=user_guide]\n----\n<1> Get the store from the launcher session\n<2> Lazily create the HTTP server and put it into the store\n<3> Start the HTTP server\n\nIt uses a wrapper class to ensure the server is stopped when the launcher session is\nclosed:\n\n[source,java]\n.src/test/java/example/session/CloseableHttpServer.java\n----\npackage example.session;\n\ninclude::example$java/example/session/CloseableHttpServer.java[tags=user_guide]\n----\n<1> The `close()` method is called when the launcher session is closed\n<2> Stop the HTTP server\n\nThis sample uses the HTTP server implementation from the jdk.httpserver module that comes\nwith the JDK but would work similarly with any other server or resource. In order for the\nlistener to be picked up by JUnit Platform, you need to register it as a service by adding\na resource file with the following name and contents to your test runtime classpath (e.g.\nby adding the file to `src/test/resources`):\n\n[source]\n.src/test/resources/META-INF/services/org.junit.platform.launcher.LauncherSessionListener\n----\ninclude::example$resources/META-INF/services/org.junit.platform.launcher.LauncherSessionListener[]\n----\n\nYou can now use the resource from your test:\n\n[source,java]\n.src/test/java/example/session/HttpTests.java\n----\npackage example.session;\n\ninclude::example$java/example/session/HttpTests.java[tags=user_guide]\n----\n<1> Retrieve the HTTP server instance from the store\n<2> Get the host string directly from the injected HTTP server instance\n<3> Get the port number directly from the injected HTTP server instance\n<4> Send a request to the server\n<5> Check the status code of the response\n\n[[launcher-interceptors-custom]]\n== Registering a LauncherInterceptor\n\nIn order to intercept the creation of instances of `{Launcher}` and\n`{LauncherSessionListener}` and calls to the `discover` and `execute` methods of the\nformer, clients can register custom implementations of `{LauncherInterceptor}` via Java's\n`{ServiceLoader}` mechanism by setting the\n`junit.platform.launcher.interceptors.enabled` xref:running-tests/configuration-parameters.adoc[configuration parameter] to `true`.\n\n[NOTE]\n====\nSince interceptors are registered before the test run starts, the\n`junit.platform.launcher.interceptors.enabled` _configuration parameter_ can only be\nsupplied as a JVM system property or via the JUnit Platform configuration file (see\nxref:running-tests/configuration-parameters.adoc[] for details). This _configuration parameter_ cannot be\nsupplied in the `LauncherDiscoveryRequest` that is passed to the `{Launcher}`.\n====\n\n\nA typical use case is to create a custom interceptor to replace the `ClassLoader` used by\nthe JUnit Platform to load test classes and engine implementations.\n\n[source,java]\n----\ninclude::example$java/example/CustomLauncherInterceptor.java[tags=user_guide]\n----\n\n[[launcher-discovery-listeners-custom]]\n== Registering a LauncherDiscoveryListener\n\nIn addition to specifying discovery listeners as part of a `{LauncherDiscoveryRequest}` or\nregistering them programmatically via the `{Launcher}` API, custom\n`LauncherDiscoveryListener` implementations can be discovered at runtime via Java's\n`{ServiceLoader}` mechanism and automatically registered with the `Launcher` created via\nthe `{LauncherFactory}`.\n\nFor example, an `example.CustomLauncherDiscoveryListener` class implementing\n`LauncherDiscoveryListener` and declared within the\n`/META-INF/services/org.junit.platform.launcher.LauncherDiscoveryListener` file is loaded\nand registered automatically.\n\n[[listeners-custom]]\n== Registering a TestExecutionListener\n\nIn addition to the public `{Launcher}` API method for registering test execution listeners\nprogrammatically, custom `{TestExecutionListener}` implementations will be discovered at\nruntime via Java's `{ServiceLoader}` mechanism and automatically registered with the\n`Launcher` created via the `{LauncherFactory}`.\n\nFor example, an `example.CustomTestExecutionListener` class implementing\n`TestExecutionListener` and declared within the\n`/META-INF/services/org.junit.platform.launcher.TestExecutionListener` file is loaded and\nregistered automatically.\n\n[[listeners-config]]\n== Configuring a TestExecutionListener\n\nWhen a `{TestExecutionListener}` is registered programmatically via the `{Launcher}` API,\nthe listener may provide programmatic ways for it to be configured -- for example, via its\nconstructor, setter methods, etc. However, when a `TestExecutionListener` is registered\nautomatically via Java's `ServiceLoader` mechanism (see\n<>), there is no way for the user to directly configure the\nlistener. In such cases, the author of a `TestExecutionListener` may choose to make the\nlistener configurable via xref:running-tests/configuration-parameters.adoc[configuration parameters]. The\nlistener can then access the configuration parameters via the `TestPlan` supplied to the\n`testPlanExecutionStarted(TestPlan)` and `testPlanExecutionFinished(TestPlan)` callback\nmethods. See the `{UniqueIdTrackingListener}` for an example.\n\n[[listeners-custom-deactivation]]\n== Deactivating a TestExecutionListener\n\nSometimes it can be useful to run a test suite _without_ certain execution listeners being\nactive. For example, you might have custom a `{TestExecutionListener}` that sends the test\nresults to an external system for reporting purposes, and while debugging you might not\nwant these _debug_ results to be reported. To do this, provide a pattern for the\n`junit.platform.execution.listeners.deactivate` _configuration parameter_ to specify which\nexecution listeners should be deactivated (i.e. not registered) for the current test run.\n\n[NOTE]\n====\nOnly listeners registered via the `{ServiceLoader}` mechanism within the\n`/META-INF/services/org.junit.platform.launcher.TestExecutionListener` file can be\ndeactivated. In other words, any `TestExecutionListener` registered explicitly via the\n`{LauncherDiscoveryRequest}` cannot be deactivated via the\n`junit.platform.execution.listeners.deactivate` _configuration parameter_.\n\nIn addition, since execution listeners are registered before the test run starts, the\n`junit.platform.execution.listeners.deactivate` _configuration parameter_ can only be\nsupplied as a JVM system property or via the JUnit Platform configuration file (see\nxref:running-tests/configuration-parameters.adoc[] for details). This _configuration parameter_ cannot be\nsupplied in the `LauncherDiscoveryRequest` that is passed to the `{Launcher}`.\n====\n\n[[listeners-custom-deactivation-pattern]]\n=== Pattern Matching Syntax\n\nRefer to xref:running-tests/configuration-parameters.adoc#pattern[Pattern Matching Syntax] for details.\n\n[[launcher-config]]\n== Configuring the Launcher\n\nIf you require fine-grained control over automatic detection and registration of test\nengines and listeners, you may create an instance of `{LauncherConfig}` and supply that to\nthe `{LauncherFactory}`. Typically, an instance of `LauncherConfig` is created via the\nbuilt-in fluent _builder_ API, as demonstrated in the following example.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/UsingTheLauncherDemo.java[tags=launcherConfig]\n----\n\n[[dry-run-mode]]\n== Dry-Run Mode\n\nWhen running tests via the `{Launcher}` API, you can enable _dry-run mode_ by setting the\n`junit.platform.execution.dryRun.enabled` xref:running-tests/configuration-parameters.adoc[configuration parameter] to `true`. In this mode, the `{Launcher}` will not actually\nexecute any tests but will notify registered `{TestExecutionListener}` instances as if all\ntests had been skipped and their containers had been successful. This can be useful to\ntest changes in the configuration of a build or to verify a listener is called as expected\nwithout having to wait for all tests to be executed.\n\n[[managing-state-across-test-engines]]\n== Managing State Across Test Engines\n\nWhen running tests on the JUnit Platform, multiple test engines may need to access shared\nresources. Rather than initializing these resources multiple times, JUnit Platform\nprovides mechanisms to share state across test engines efficiently. Test engines can use\nthe Platform's `{NamespacedHierarchicalStore}` API to lazily initialize and share\nresources, ensuring they are created only once regardless of execution order. Any resource\nthat is put into the store and implements `AutoCloseable` will be closed automatically when\nthe execution is finished.\n\nTIP: The Jupiter engine allows read and write access to such resources via its\n`{ExtensionContext_Store}` API.\n\nThe following example demonstrates two custom test engines sharing a `ServerSocket`\nresource. `FirstCustomEngine` attempts to retrieve an existing `ServerSocket` from the\nglobal store or creates a new one if it doesn't exist:\n\n[source,java]\n----\ninclude::example$java/example/FirstCustomEngine.java[tags=user_guide]\n----\n\n`SecondCustomEngine` follows the same pattern, ensuring that regardless whether it runs\nbefore or after `FirstCustomEngine`, it will use the same socket instance:\n\n[source,java]\n----\ninclude::example$java/example/SecondCustomEngine.java[tags=user_guide]\n----\n\nTIP: In this case, the `ServerSocket` can be stored directly in the global store while\nensuring since it gets closed because it implements `AutoCloseable`. If you need to use a\ntype that does not do so, you can wrap it in a custom class that implements\n`AutoCloseable` and delegates to the original type. This is important to ensure that the\nresource is closed properly when the test run is finished.\n\nFor illustration, the following test verifies that both engines are sharing the same\n`ServerSocket` instance and that it's closed after `Launcher.execute()` returns:\n\n[source,java,indent=0]\n----\ninclude::example$java/example/sharedresources/SharedResourceDemo.java[tags=user_guide]\n----\n\nBy using the Platform's `{NamespacedHierarchicalStore}` API with shared namespaces in this\nway, test engines can coordinate resource creation and sharing without direct dependencies\nbetween them.\n\nAlternatively, it's possible to inject resources into test engines by\n<>.\n\n[[launcher-cancellation]]\n== Cancelling a Running Test Execution\n\nThe launcher API provides the ability to cancel a running test execution mid-flight while\nallowing engines to clean up resources. To request an execution to be cancelled, you need\nto call `cancel()` on the `{CancellationToken}` that is passed to `Launcher.execute` as\npart of the `{LauncherExecutionRequest}`.\n\nFor example, implementing a listener that cancels test execution after the first test\nfailed can be achieved as follows.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/UsingTheLauncherDemo.java[tags=cancellation-direct]\n----\n<1> Create a `{CancellationToken}`\n<2> Implement a `{TestExecutionListener}` that calls `cancel()` when a test fails\n<3> Register the cancellation token\n<4> Register the listener\n<5> Pass the `{LauncherExecutionRequest}` to `Launcher.execute`\n\n[NOTE]\n.Test Engine Support for Cancellation\n====\nCancelling tests relies on xref:advanced-topics/engines.adoc[] checking and responding to the\n`{CancellationToken}` appropriately (see\nxref:advanced-topics/engines.adoc#requirements-cancellation[Test Engine Requirements] for details). The\n`Launcher` will also check the token and cancel test execution when multiple test engines\nare present at runtime.\n\nAt the time of writing, the following test engines support cancellation:\n\n* `{junit-jupiter-engine}`\n* `{junit-vintage-engine}`\n* `{junit-platform-suite-engine}`\n* https://github.com/junit-team/testng-engine[`testng-engine`] (version 1.1.0 and later)\n* Any `{TestEngine}` extending `{HierarchicalTestEngine}` such as Spock and Cucumber\n====\n\n[[launcher-cancellation-execution-request-from-discovery-request]]\n=== Building a LauncherExecutionRequest from a LauncherDiscoveryRequest\n\nRather than building a `{LauncherExecutionRequest}` by starting with a\n`{LauncherDiscoveryRequestBuilder}` and calling `forExecution()`, you can create a\n`{LauncherExecutionRequestBuilder}` from a previously built `{LauncherDiscoveryRequest}`.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/UsingTheLauncherDemo.java[tags=cancellation-discovery-request]\n----\n<1> Build a `{LauncherDiscoveryRequest}`\n<2> Create a `{LauncherExecutionRequestBuilder}` with it\n<3> Register the cancellation token\n<4> Register the listener\n<5> Pass the `{LauncherExecutionRequest}` to `Launcher.execute`\n\n[[launcher-cancellation-execution-request-from-test-plan]]\n=== Building a LauncherExecutionRequest from a TestPlan\n\nAlternatively, a `{LauncherExecutionRequestBuilder}` can be created from a previously\ndiscovered `{TestPlan}`.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/UsingTheLauncherDemo.java[tags=cancellation-test-plan]\n----\n<1> Build a `{LauncherDiscoveryRequest}`\n<2> Discover a `{TestPlan}` via `Launcher.discover`\n<3> Create a `{LauncherExecutionRequestBuilder}` with it\n<4> Register the cancellation token\n<5> Register the listener\n<6> Pass the `{LauncherExecutionRequest}` to `Launcher.execute`\n"
},
{
"path": "documentation/modules/ROOT/pages/advanced-topics/testkit.adoc",
"content": "= JUnit Platform Test Kit\n\nThe `junit-platform-testkit` artifact provides support for executing a test plan on the\nJUnit Platform and then verifying the expected results. This support is currently limited\nto the execution of a single `TestEngine` (see <>).\n\n[[engine]]\n== Engine Test Kit\n\nThe `{testkit-engine-package}` package provides support for discovering and executing a\n`{TestPlan}` for a given `{TestEngine}` running on the JUnit Platform and then accessing\nthe results via convenient result objects. For execution, a fluent API may be used to\nverify the expected execution events were received. The key entry point into this API is\nthe `{EngineTestKit}` which provides static factory methods named `engine()`,\n`discover()`, and `execute()`. It is recommended that you select one of the `engine()`\nvariants to benefit from the fluent API for building a `LauncherDiscoveryRequest`.\n\nNOTE: If you prefer to use the `LauncherDiscoveryRequestBuilder` from the `Launcher` API\nto build your `LauncherDiscoveryRequest`, you must use one of the `discover()` or\n`execute()` variants in `EngineTestKit`.\n\nThe following test class written using JUnit Jupiter will be used in subsequent examples.\n\n[[engine-ExampleTestCase]]\n[source,java,indent=0]\n----\ninclude::example$java/example/ExampleTestCase.java[tags=user_guide]\n----\n\nFor the sake of brevity, the following sections demonstrate how to test JUnit's own\n`JupiterTestEngine` whose unique engine ID is `\"junit-jupiter\"`. If you want to test your\nown `TestEngine` implementation, you need to use its unique engine ID. Alternatively, you\nmay test your own `TestEngine` by supplying an instance of it to the\n`EngineTestKit.engine(TestEngine)` static factory method.\n\n[[engine-discovery]]\n== Verifying Test Discovery\n\nThe following test demonstrates how to verify that a `TestPlan` was discovered as expected\nby the JUnit Jupiter `TestEngine`.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/testkit/EngineTestKitDiscoveryDemo.java[tags=user_guide]\n----\n<1> Select the JUnit Jupiter `TestEngine`.\n<2> Select the <> test class.\n<3> Discover the `TestPlan`.\n<4> Assert engine root descriptor has expected display name.\n<5> Assert no discovery issues were encountered.\n\n[[engine-statistics]]\n== Asserting Execution Statistics\n\nOne of the most common features of the Test Kit is the ability to assert statistics\nagainst events fired during the execution of a `TestPlan`. The following tests demonstrate\nhow to assert statistics for _containers_ and _tests_ in the JUnit Jupiter `TestEngine`.\nFor details on what statistics are available, consult the Javadoc for `{EventStatistics}`.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/testkit/EngineTestKitStatisticsDemo.java[tags=user_guide]\n----\n<1> Select the JUnit Jupiter `TestEngine`.\n<2> Select the <> test class.\n<3> Execute the `TestPlan`.\n<4> Filter by _container_ events.\n<5> Assert statistics for _container_ events.\n<6> Filter by _test_ events.\n<7> Assert statistics for _test_ events.\n\nNOTE: In the `verifyJupiterContainerStats()` test method, the counts for the `started` and\n`succeeded` statistics are `2` since the `JupiterTestEngine` and the\n<> class are both considered containers.\n\n[[engine-events]]\n== Asserting Events\n\nIf you find that <> alone is insufficient\nfor verifying the expected behavior of test execution, you can work directly with the\nrecorded `{Event}` elements and perform assertions against them.\n\nFor example, if you want to verify the reason that the `skippedTest()` method in\n<> was skipped, you can do that as\nfollows.\n\n[TIP]\n====\nThe `assertThatEvents()` method in the following example is a shortcut for\n`org.assertj.core.api.Assertions.assertThat(events.list())` from the {AssertJ} assertion\nlibrary.\n\nFor details on what _conditions_ are available for use with AssertJ assertions against\nevents, consult the Javadoc for `{EventConditions}`.\n====\n\n[source,java,indent=0]\n----\ninclude::example$java/example/testkit/EngineTestKitSkippedMethodDemo.java[tags=user_guide]\n----\n<1> Select the JUnit Jupiter `TestEngine`.\n<2> Select the `skippedTest()` method in the <> test class.\n<3> Execute the `TestPlan`.\n<4> Filter by _test_ events.\n<5> Save the _test_ `Events` to a local variable.\n<6> Optionally assert the expected statistics.\n<7> Assert that the recorded _test_ events contain exactly one skipped test named\n `skippedTest` with `\"for demonstration purposes\"` as the _reason_.\n\nIf you want to verify the type of exception thrown from the `failingTest()` method in\n<>, you can do that as follows.\n\n[TIP]\n====\nFor details on what _conditions_ are available for use with AssertJ assertions against\nevents and execution results, consult the Javadoc for `{EventConditions}` and\n`{TestExecutionResultConditions}`, respectively.\n====\n\n[source,java,indent=0]\n----\ninclude::example$java/example/testkit/EngineTestKitFailedMethodDemo.java[tags=user_guide]\n----\n<1> Select the JUnit Jupiter `TestEngine`.\n<2> Select the <> test class.\n<3> Execute the `TestPlan`.\n<4> Filter by _test_ events.\n<5> Assert that the recorded _test_ events contain exactly one failing test named\n `failingTest` with an exception of type `ArithmeticException` and an error message\n that ends with `\"/ by zero\"`.\n\nAlthough typically unnecessary, there are times when you need to verify **all** of the\nevents fired during the execution of a `TestPlan`. The following test demonstrates how to\nachieve this via the `assertEventsMatchExactly()` method in the `EngineTestKit` API.\n\n[TIP]\n====\nSince `assertEventsMatchExactly()` matches conditions exactly in the order in which the\nevents were fired, <> has been\nannotated with `@TestMethodOrder(OrderAnnotation.class)` and each test method has been\nannotated with `@Order(...)`. This allows us to enforce the order in which the test\nmethods are executed, which in turn allows our `verifyAllJupiterEvents()` test to be\nreliable.\n====\n\nIf you want to do a _partial_ match _with_ or _without_ ordering requirements, you can use\nthe methods `assertEventsMatchLooselyInOrder()` and `assertEventsMatchLoosely()`,\nrespectively.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/testkit/EngineTestKitAllEventsDemo.java[tags=user_guide]\n----\n<1> Select the JUnit Jupiter `TestEngine`.\n<2> Select the <> test class.\n<3> Execute the `TestPlan`.\n<4> Filter by _all_ events.\n<5> Print all events to the supplied `writer` for debugging purposes. Debug information\n can also be written to an `OutputStream` such as `System.out` or `System.err`.\n<6> Assert _all_ events in exactly the order in which they were fired by the test engine.\n\nThe `debug()` invocation from the preceding example results in output similar to the\nfollowing.\n\n[source,options=\"nowrap\"]\n----\nAll Events:\n\tEvent [type = STARTED, testDescriptor = JupiterEngineDescriptor: [engine:junit-jupiter], timestamp = 2018-12-14T12:45:14.082280Z, payload = null]\n\tEvent [type = STARTED, testDescriptor = ClassTestDescriptor: [engine:junit-jupiter]/[class:example.ExampleTestCase], timestamp = 2018-12-14T12:45:14.089339Z, payload = null]\n\tEvent [type = SKIPPED, testDescriptor = TestMethodTestDescriptor: [engine:junit-jupiter]/[class:example.ExampleTestCase]/[method:skippedTest()], timestamp = 2018-12-14T12:45:14.094314Z, payload = 'for demonstration purposes']\n\tEvent [type = STARTED, testDescriptor = TestMethodTestDescriptor: [engine:junit-jupiter]/[class:example.ExampleTestCase]/[method:succeedingTest()], timestamp = 2018-12-14T12:45:14.095182Z, payload = null]\n\tEvent [type = FINISHED, testDescriptor = TestMethodTestDescriptor: [engine:junit-jupiter]/[class:example.ExampleTestCase]/[method:succeedingTest()], timestamp = 2018-12-14T12:45:14.104922Z, payload = TestExecutionResult [status = SUCCESSFUL, throwable = null]]\n\tEvent [type = STARTED, testDescriptor = TestMethodTestDescriptor: [engine:junit-jupiter]/[class:example.ExampleTestCase]/[method:abortedTest()], timestamp = 2018-12-14T12:45:14.106121Z, payload = null]\n\tEvent [type = FINISHED, testDescriptor = TestMethodTestDescriptor: [engine:junit-jupiter]/[class:example.ExampleTestCase]/[method:abortedTest()], timestamp = 2018-12-14T12:45:14.109956Z, payload = TestExecutionResult [status = ABORTED, throwable = org.opentest4j.TestAbortedException: Assumption failed: abc does not contain Z]]\n\tEvent [type = STARTED, testDescriptor = TestMethodTestDescriptor: [engine:junit-jupiter]/[class:example.ExampleTestCase]/[method:failingTest()], timestamp = 2018-12-14T12:45:14.110680Z, payload = null]\n\tEvent [type = FINISHED, testDescriptor = TestMethodTestDescriptor: [engine:junit-jupiter]/[class:example.ExampleTestCase]/[method:failingTest()], timestamp = 2018-12-14T12:45:14.111217Z, payload = TestExecutionResult [status = FAILED, throwable = java.lang.ArithmeticException: / by zero]]\n\tEvent [type = FINISHED, testDescriptor = ClassTestDescriptor: [engine:junit-jupiter]/[class:example.ExampleTestCase], timestamp = 2018-12-14T12:45:14.113731Z, payload = TestExecutionResult [status = SUCCESSFUL, throwable = null]]\n\tEvent [type = FINISHED, testDescriptor = JupiterEngineDescriptor: [engine:junit-jupiter], timestamp = 2018-12-14T12:45:14.113806Z, payload = TestExecutionResult [status = SUCCESSFUL, throwable = null]]\n----\n"
},
{
"path": "documentation/modules/ROOT/pages/api-evolution.adoc",
"content": "= API Evolution\n:page-toclevels: 1\n\nOne of the major goals of the JUnit Platform architecture is to improve maintainers'\ncapabilities to evolve JUnit despite its being used in many projects. With JUnit 4 a lot\nof stuff that was originally added as an internal construct only got used by external\nextension writers and tool builders. That made changing JUnit 4 especially difficult and\nsometimes impossible.\n\nThat's why JUnit now uses a defined lifecycle for all publicly available interfaces,\nclasses, and methods.\n\n[[version-and-status]]\n== API Version and Status\n\nEvery published artifact has a version number `..`, and all publicly\navailable interfaces, classes, and methods are annotated with {API} from the\n{API_Guardian} project. The annotation's `status` attribute can be assigned one of the\nfollowing values.\n\n[cols=\"20,80\"]\n|===\n| Status | Description\n\n| `INTERNAL` | Must not be used by any code other than JUnit itself. Might be removed without prior notice.\n| `DEPRECATED` | Should no longer be used; might disappear in the next minor release.\n| `EXPERIMENTAL` | Intended for new, experimental features where we are looking for feedback. +\n Use this element with caution; it might be promoted to `MAINTAINED` or\n `STABLE` in the future, but might also be removed without prior notice, even in a patch.\n| `MAINTAINED` | Intended for features that will not be changed in a backwards-\n incompatible way for *at least* the next minor release of the current\n major version. If scheduled for removal, it will be demoted to `DEPRECATED` first.\n| `STABLE` | Intended for features that will not be changed in a backwards-\n incompatible way in the current major version (`6.*`).\n|===\n\nIf the `@API` annotation is present on a type, it is considered to be applicable for all\npublic members of that type as well. A member is allowed to declare a different `status`\nvalue of lower stability.\n\n[[experimental-apis]]\n== Experimental APIs\n\nThe following tables list which APIs are currently designated as _experimental_ via\n`@API(status = EXPERIMENTAL)`. Caution should be taken when relying on such APIs.\n\ninclude::partial$experimental-apis-table.adoc[]\n\n[[deprecated-apis]]\n== Deprecated APIs\n\nThe following tables list which APIs are currently designated as _deprecated_ via\n`@API(status = DEPRECATED)`. You should avoid using deprecated APIs whenever possible,\nsince such APIs will likely be removed in an upcoming release.\n\ninclude::partial$deprecated-apis-table.adoc[]\n\n[[tooling]]\n== @API Tooling Support\n\nThe {API_Guardian} project plans to provide tooling support for publishers and consumers\nof APIs annotated with {API}. For example, the tooling support will likely provide a\nmeans to check if JUnit APIs are being used in accordance with `@API` annotation\ndeclarations.\n"
},
{
"path": "documentation/modules/ROOT/pages/appendix.adoc",
"content": "= Appendix\n\n[[reproducible-builds]]\n== Reproducible Builds\n\nJUnit aims for its non-javadoc JARs to be https://reproducible-builds.org/[reproducible].\n\nUnder identical build conditions, such as Java version, repeated builds should provide the\nsame output byte-for-byte.\n\nThis means that anyone can reproduce the build conditions of the artifacts on Maven\nCentral/Sonatype and produce the same output artifact locally, confirming that the\nartifacts in the repositories were actually generated from this source code.\n\n[[dependency-metadata]]\n== Dependency Metadata\n\nArtifacts for final releases and milestones are deployed to {Maven_Central}. Consult\nhttps://central.sonatype.org/consume/[Sonatype's documentation] for how to consume those\nartifacts with a build tool of your choice.\n\nSnapshot artifacts are deployed to Sonatype's {snapshot-repo}[snapshots repository]\nunder {snapshot-repo}/org/junit/[/org/junit]. Please refer to\nhttps://central.sonatype.org/publish/publish-portal-snapshots/#consuming-snapshot-releases-for-your-project[Sonatype's documentation]\nfor instructions on how to consume them with a build tool of your choice.\n\nThe sections below list all artifacts with their versions for the three groups:\n<>,\n<>, and\n<>.\nThe <> contains a list of all\nof the above artifacts and their versions.\n\n[TIP]\n.Aligning dependency versions\n====\nTo ensure that all JUnit artifacts are compatible with each other, their versions should\nbe aligned.\nIf you rely on xref:running-tests/build-support.adoc#spring-boot[Spring Boot] for dependency management,\nplease see the corresponding section.\nOtherwise, instead of managing individual versions of the JUnit artifacts, it is\nrecommended to apply the <> to your project.\nPlease refer to the corresponding sections for xref:running-tests/build-support.adoc#maven-bom[Maven] or\nxref:running-tests/build-support.adoc#gradle-bom[Gradle].\n====\n\n[[dependency-metadata-junit-platform]]\n=== JUnit Platform\n\n* *Group ID*: `org.junit.platform`\n* *Version*: `{version}`\n* *Artifact IDs*:\n `junit-platform-commons`::\n Common APIs and support utilities for the JUnit Platform. Any API annotated with\n `@API(status = INTERNAL)` is intended solely for usage within the JUnit framework\n itself. _Any usage of internal APIs by external parties is not supported!_\n `junit-platform-console`::\n Support for discovering and executing tests on the JUnit Platform from the console.\n See xref:running-tests/console-launcher.adoc[] for details.\n `junit-platform-console-standalone`::\n An executable _Fat JAR_ that contains all dependencies is provided in Maven Central under the\n https://repo1.maven.org/maven2/org/junit/platform/junit-platform-console-standalone[junit-platform-console-standalone]\n directory. See xref:running-tests/console-launcher.adoc[] for details.\n `junit-platform-engine`::\n Public API for test engines. See xref:advanced-topics/launcher-api.adoc#engines-custom[Registering a TestEngine] for details.\n `junit-platform-launcher`::\n Public API for configuring and launching test plans -- typically used by IDEs and\n build tools. See xref:advanced-topics/launcher-api.adoc[] for details.\n `junit-platform-reporting`::\n `TestExecutionListener` implementations that generate test reports -- typically used\n by IDEs and build tools. See xref:advanced-topics/junit-platform-reporting.adoc[] for details.\n `junit-platform-suite`::\n JUnit Platform Suite artifact that transitively pulls in dependencies on\n `junit-platform-suite-api` and `junit-platform-suite-engine` for simplified dependency\n\tmanagement in build tools such as Gradle and Maven.\n `junit-platform-suite-api`::\n Annotations for configuring test suites on the JUnit Platform. Supported by the\n xref:advanced-topics/junit-platform-suite-engine.adoc[JUnit Platform Suite Engine].\n `junit-platform-suite-engine`::\n Engine that executes test suites on the JUnit Platform; only required at runtime. See\n xref:advanced-topics/junit-platform-suite-engine.adoc[JUnit Platform Suite Engine] for details.\n `junit-platform-testkit`::\n Provides support for executing a test plan for a given `TestEngine` and then\n accessing the results via a fluent API to verify the expected results.\n\n[[dependency-metadata-junit-jupiter]]\n=== JUnit Jupiter\n\n* *Group ID*: `org.junit.jupiter`\n* *Version*: `{version}`\n* *Artifact IDs*:\n `junit-jupiter`::\n JUnit Jupiter aggregator artifact that transitively pulls in dependencies on\n `junit-jupiter-api`, `junit-jupiter-params`, and `junit-jupiter-engine` for\n simplified dependency management in build tools such as Gradle and Maven.\n `junit-jupiter-api`::\n JUnit Jupiter API for xref:writing-tests/intro.adoc[writing tests] and xref:extensions/overview.adoc[extensions].\n `junit-jupiter-engine`::\n JUnit Jupiter test engine implementation; only required at runtime.\n `junit-jupiter-params`::\n Support for xref:writing-tests/parameterized-classes-and-tests.adoc[] in JUnit Jupiter.\n `junit-jupiter-migrationsupport`::\n _Deprecated_ support for migrating from JUnit 4 to JUnit Jupiter; only required for\n support for JUnit 4's `@Ignore` annotation and for running selected JUnit 4 rules.\n\n[[dependency-metadata-junit-vintage]]\n=== JUnit Vintage\n\n* *Group ID*: `org.junit.vintage`\n* *Version*: `{version}`\n* *Artifact ID*:\n `junit-vintage-engine`::\n JUnit Vintage test engine implementation that allows one to run _vintage_ JUnit tests\n on the JUnit Platform. _Vintage_ tests include those written using JUnit 3 or JUnit 4\n APIs or tests written using testing frameworks built on those APIs.\n\n[[dependency-metadata-junit-bom]]\n=== Bill of Materials (BOM)\n\nThe _Bill of Materials_ POM provided under the following Maven coordinates can be used to\nease dependency management when referencing multiple of the above artifacts using\nxref:running-tests/build-support.adoc#maven-bom[Maven] or\nxref:running-tests/build-support.adoc#gradle-bom[Gradle].\n\n* *Group ID*: `org.junit`\n* *Artifact ID*: `junit-bom`\n* *Version*: `{version}`\n\n[[dependency-metadata-dependencies]]\n=== Dependencies\n\nMost of the above artifacts have a dependency in their published Maven POMs on the\nfollowing _@API Guardian_ JAR.\n\n* *Group ID*: `org.apiguardian`\n* *Artifact ID*: `apiguardian-api`\n* *Version*: `{apiguardian-version}`\n\nIn addition, most of the above artifacts have a direct or transitive dependency on the\nfollowing _OpenTest4J_ JAR.\n\n* *Group ID*: `org.opentest4j`\n* *Artifact ID*: `opentest4j`\n* *Version*: `{ota4j-version}`\n\n[[dependency-diagram]]\n== Dependency Diagram\n\nimage::component-diagram.svg[]\n"
},
{
"path": "documentation/modules/ROOT/pages/extensions/conditional-test-execution.adoc",
"content": "= Conditional Test Execution\n\n`{ExecutionCondition}` defines the `Extension` API for programmatic, _conditional test\nexecution_.\n\nAn `ExecutionCondition` is _evaluated_ for each container (e.g., a test class) to\ndetermine if all the tests it contains should be executed based on the supplied\n`ExtensionContext`. Similarly, an `ExecutionCondition` is _evaluated_ for each test to\ndetermine if a given test method should be executed based on the supplied\n`ExtensionContext`.\n\nWhen multiple `ExecutionCondition` extensions are registered, a container or test is\ndisabled as soon as one of the conditions returns _disabled_. Thus, there is no guarantee\nthat a condition is evaluated because another extension might have already caused a\ncontainer or test to be disabled. In other words, the evaluation works like the\nshort-circuiting boolean OR operator.\n\nSee the source code of `{DisabledCondition}` and `{Disabled}` for concrete examples.\n\n[[deactivation]]\n== Deactivating Conditions\n\nSometimes it can be useful to run a test suite _without_ certain conditions being active.\nFor example, you may wish to run tests even if they are annotated with `@Disabled` in\norder to see if they are still _broken_. To do this, provide a pattern for the\n`junit.jupiter.conditions.deactivate` _configuration parameter_ to specify which\nconditions should be deactivated (i.e., not evaluated) for the current test run. The\npattern can be supplied as a JVM system property, as a _configuration parameter_ in the\n`LauncherDiscoveryRequest` that is passed to the `Launcher`, or via the JUnit Platform\nconfiguration file (see xref:running-tests/configuration-parameters.adoc[] for details).\n\nFor example, to deactivate JUnit's `@Disabled` condition, you can start your JVM with the\nfollowing system property.\n\n`-Djunit.jupiter.conditions.deactivate=org.junit.*DisabledCondition`\n\n[[deactivation-patterns]]\n=== Pattern Matching Syntax\n\nRefer to xref:running-tests/configuration-parameters.adoc#pattern[Pattern Matching Syntax] for details.\n"
},
{
"path": "documentation/modules/ROOT/pages/extensions/exception-handling.adoc",
"content": "= Exception Handling\n\nExceptions thrown during the test execution may be intercepted and handled accordingly\nbefore propagating further, so that certain actions like error logging or resource releasing\nmay be defined in specialized `Extensions`. JUnit Jupiter offers API for `Extensions` that\nwish to handle exceptions thrown during `@Test` methods via `{TestExecutionExceptionHandler}`\nand for those thrown during one of test lifecycle methods (`@BeforeAll`, `@BeforeEach`,\n`@AfterEach` and `@AfterAll`) via `{LifecycleMethodExecutionExceptionHandler}`.\n\nThe following example shows an extension which will swallow all instances of `IOException`\nbut rethrow any other type of exception.\n\n[source,java,indent=0]\n.An exception handling extension that filters IOExceptions in test execution\n----\ninclude::example$java/example/exception/IgnoreIOExceptionExtension.java[tags=user_guide]\n----\n\nAnother example shows how to record the state of an application under test exactly at\nthe point of unexpected exception being thrown during setup and cleanup. Note that unlike\nrelying on lifecycle callbacks, which may or may not be executed depending on the test\nstatus, this solution guarantees execution immediately after failing `@BeforeAll`,\n`@BeforeEach`, `@AfterEach` or `@AfterAll`.\n\n[source,java,indent=0]\n.An exception handling extension that records application state on error\n----\ninclude::example$java/example/exception/RecordStateOnErrorExtension.java[tags=user_guide]\n----\n\nMultiple execution exception handlers may be invoked for the same lifecycle method in\norder of declaration. If one of the handlers swallows the handled exception, subsequent\nones will not be executed, and no failure will be propagated to JUnit engine, as if the\nexception was never thrown. Handlers may also choose to rethrow the exception or throw\na different one, potentially wrapping the original.\n\nExtensions implementing `{LifecycleMethodExecutionExceptionHandler}` that wish to handle\nexceptions thrown during `@BeforeAll` or `@AfterAll` need to be registered on a class level,\nwhile handlers for `BeforeEach` and `AfterEach` may be also registered for individual\ntest methods.\n\n[source,java,indent=0]\n.Registering multiple exception handling extensions\n----\ninclude::example$java/example/exception/MultipleHandlersTestCase.java[tags=user_guide]\n----\n"
},
{
"path": "documentation/modules/ROOT/pages/extensions/intercepting-invocations.adoc",
"content": "= Intercepting Invocations\n\n`{InvocationInterceptor}` defines the API for `Extensions` that wish to intercept calls to\ntest code.\n\nThe following example shows an extension that executes all test methods in Swing's Event\nDispatch Thread.\n\n[source,java,indent=0]\n.An extension that executes tests in a user-defined thread\n----\ninclude::example$java/example/interceptor/SwingEdtInterceptor.java[tags=user_guide]\n----\n\n[NOTE]\n.Accessing the test-scoped `ExtensionContext`\n====\nYou may override the `getTestInstantiationExtensionContextScope(...)` method to return\n`TEST_METHOD` to make test-specific data available to your extension implementation of\n`interceptTestClassConstructor` or if you want to xref:extensions/keeping-state-in-extensions.adoc[keep state]\non the test method level.\n====\n"
},
{
"path": "documentation/modules/ROOT/pages/extensions/keeping-state-in-extensions.adoc",
"content": "= Keeping State in Extensions\n\nUsually, an extension is instantiated only once. So the question becomes relevant: How do\nyou keep the state from one invocation of an extension to the next? The\n`{ExtensionContext}` API provides a `{ExtensionContext_Store}` exactly for this purpose.\nExtensions may put values into a store for later retrieval.\n\nTIP: See the `xref:extensions/test-lifecycle-callbacks.adoc#timing-extension[TimingExtension]` for an\nexample of using the `Store` with a method-level scope.\n\n.The `ExtensionContext` and `Store` hierarchy\nimage::extensions_StoreHierarchy.svg[alt=UML diagram,role=text-center]\n\nAs illustrated by the diagram above, stores are hierarchical in nature. When looking up a\nvalue, if no value is stored in the current `ExtensionContext` for the supplied key, the\nstores of the context's ancestors will be queried for a value with the same key in the\n`Namespace` used to create this store. The root `ExtensionContext` represents the engine\nlevel so its `Store` may be used to store or cache values that are used by multiple test\nclasses or extension. The `{ExtensionContext_StoreScope}` enum allows to go beyond even\nthat and access the stores on the level of the current `{LauncherExecutionRequest}` or\n`{LauncherSession}` which can be used to share data across test engines or inject data\nfrom a registered\nxref:advanced-topics/launcher-api.adoc#launcher-session-listeners-custom[`LauncherSessionListener`],\nrespectively. Please consult the Javadoc of `{ExtensionContext}`,\n`{ExtensionContext_Store}`, and `{ExtensionContext_StoreScope}` for details.\n\n[[support]]\n[NOTE]\n.Resource management via `_AutoCloseable_`\n====\nAn extension context store is bound to its extension context lifecycle. When an extension\ncontext lifecycle ends it closes its associated store.\n\nAll stored values that are instances of `AutoCloseable` are notified by an invocation of\ntheir `close()` method in the inverse order they were added in (unless the\n`junit.jupiter.extensions.store.close.autocloseable.enabled`\nxref:running-tests/configuration-parameters.adoc[configuration parameter] is set to `false`).\n\nVersions prior to 5.13 only supported `CloseableResource`, which is deprecated but still\navailable for backward compatibility.\n====\n\nAn example implementation of `AutoCloseable` is shown below, using an `HttpServer`\nresource.\n\n.`_HttpServer_` resource implementing `_AutoCloseable_`\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/extensions/HttpServerResource.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/extensions/HttpServerResource.kt[tags=user_guide]\n----\n--\n====\n\nThis resource can then be stored in the desired `ExtensionContext`. It may be stored at\nclass or method level, if desired, but this may add unnecessary overhead for this type of\nresource. For this example it might be prudent to store it at root level and instantiate\nit lazily to ensure it's only created once per test run and reused across different test\nclasses and methods.\n\n.Lazily storing in root context with `_Store.computeIfAbsent_`\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/extensions/HttpServerExtension.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/extensions/HttpServerExtension.kt[tags=user_guide]\n----\n--\n====\n\n.A test case using the `_HttpServerExtension_`\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/HttpServerDemo.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/HttpServerDemo.kt[tags=user_guide]\n----\n--\n====\n\n[[migration]]\n[TIP]\n.Migration Note for Resource Cleanup\n======\nThe framework automatically closes resources stored in the `ExtensionContext.Store` that\nimplement `AutoCloseable`. In versions prior to 5.13, only resources implementing\n`Store.CloseableResource` were automatically closed.\n\nIf you're developing an extension that needs to support both JUnit Jupiter 5.13+ and\nearlier versions and your extension stores resources that need to be cleaned up, you\nshould implement both interfaces:\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\npublic class MyResource implements Store.CloseableResource, AutoCloseable {\n @Override\n public void close() throws Exception {\n // Resource cleanup code\n }\n}\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\nclass MyResource : Store.CloseableResource, AutoCloseable {\n override fun close() {\n // Resource cleanup code\n }\n}\n----\n--\n====\n\nThis ensures that your resource will be properly closed regardless of which JUnit Jupiter\nversion is being used.\n======\n"
},
{
"path": "documentation/modules/ROOT/pages/extensions/overview.adoc",
"content": "= Extension Model\n\nIn contrast to the competing `Runner`, `TestRule`, and `MethodRule` extension points in\nJUnit 4, the JUnit Jupiter extension model consists of a single, coherent concept: the\n`Extension` API. Note, however, that `Extension` itself is just a marker interface.\n"
},
{
"path": "documentation/modules/ROOT/pages/extensions/parameter-resolution.adoc",
"content": "= Parameter Resolution\n\n`{ParameterResolver}` defines the `Extension` API for dynamically resolving parameters at\nruntime.\n\nIf a _test class_ constructor, _test method_, or _lifecycle method_ (see\nxref:writing-tests/definitions.adoc[]) declares a parameter, the parameter must be _resolved_ at\nruntime by a `ParameterResolver`. A `ParameterResolver` can either be built-in (see\n`{TestInfoParameterResolver}`) or xref:extensions/registering-extensions.adoc[registered by the user].\nGenerally speaking, parameters may be resolved by _name_, _type_, _annotation_, or any\ncombination thereof.\n\nIf you wish to implement a custom `{ParameterResolver}` that resolves parameters based\nsolely on the type of the parameter, you may find it convenient to extend the\n`{TypeBasedParameterResolver}` which serves as a generic adapter for such use cases.\n\nFor concrete examples, consult the source code for `{CustomTypeParameterResolver}`,\n`{CustomAnnotationParameterResolver}`, and `{MapOfListsTypeBasedParameterResolver}`.\n\n[WARNING]\n====\nDue to a bug in the byte code generated by `javac` on JDK versions prior to JDK 9,\nlooking up annotations on parameters directly via the core `java.lang.reflect.Parameter`\nAPI will always fail for _inner class_ constructors (e.g., a constructor in a `@Nested`\ntest class).\n\nThe `{ParameterContext}` API supplied to `ParameterResolver` implementations therefore\nincludes the following convenience methods for correctly looking up annotations on\nparameters. Extension authors are strongly encouraged to use these methods instead of\nthose provided in `java.lang.reflect.Parameter` in order to avoid this bug in the JDK.\n\n* `boolean isAnnotated(Class annotationType)`\n* `Optional findAnnotation(Class annotationType)`\n* `List findRepeatableAnnotations(Class annotationType)`\n====\n\n[NOTE]\n.Accessing the test-scoped `ExtensionContext`\n====\nYou may override the `getTestInstantiationExtensionContextScope(...)` method to return\n`TEST_METHOD` to support injecting test specific data into constructor parameters of the\ntest class instance. Doing so causes a test-specific `{ExtensionContext}` to be used while\nresolving constructor parameters, unless the\nxref:writing-tests/test-instance-lifecycle.adoc[test instance lifecycle] is set to `PER_CLASS`.\n====\n\n[TIP]\n.Parameter resolution for methods called from extensions\n====\nOther extensions can also leverage registered `ParameterResolvers` for method and\nconstructor invocations, using the `{ExecutableInvoker}` available via the\n`getExecutableInvoker()` method in the `ExtensionContext`.\n====\n\n[[conflicts]]\n== Parameter Conflicts\n\nIf multiple implementations of `ParameterResolver` that support the same type are\nregistered for a test, a `ParameterResolutionException` will be thrown, with a\nmessage to indicate that competing resolvers have been discovered. See the following\nexample:\n\n.Conflicting parameter resolution due to multiple resolvers claiming support for integers\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/extensions/ParameterResolverConflictDemo.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/extensions/ParameterResolverConflictDemo.kt[tags=user_guide]\n----\n--\n====\n\nIf the conflicting `ParameterResolver` implementations are applied to different test\nmethods as shown in the following example, no conflict occurs.\n\n.Fine-grained registration to avoid conflict\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/extensions/ParameterResolverNoConflictDemo.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/extensions/ParameterResolverNoConflictDemo.kt[tags=user_guide]\n----\n--\n====\n\nIf the conflicting `ParameterResolver` implementations need to be applied to the same test\nmethod, you can implement a custom type or custom annotation as illustrated by\n`{CustomTypeParameterResolver}` and `{CustomAnnotationParameterResolver}`, respectively.\n\n.Custom type to resolve duplicate types\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/extensions/ParameterResolverCustomTypeDemo.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/extensions/ParameterResolverCustomTypeDemo.kt[tags=user_guide]\n----\n--\n====\n\nA custom annotation makes the duplicate type distinguishable from its counterpart:\n\n.Custom annotation to resolve duplicate types\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/extensions/ParameterResolverCustomAnnotationDemo.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/extensions/ParameterResolverCustomAnnotationDemo.kt[tags=user_guide]\n----\n--\n====\n\nJUnit includes some built-in parameter resolvers that can cause conflicts if a resolver\nattempts to claim their supported types. For example, `{TestInfo}` provides metadata about\ntests. See xref:writing-tests/dependency-injection-for-constructors-and-methods.adoc[] for details. Third-party frameworks such\nas Spring may also define parameter resolvers. Apply one of the techniques in this section\nto resolve any conflicts.\n\nParameterized tests are another potential source of conflict. Ensure that tests annotated\nwith `@ParameterizedTest` are not also annotated with `@Test` and see\nxref:writing-tests/parameterized-classes-and-tests.adoc#consuming-arguments[Consuming Arguments] for more details.\n"
},
{
"path": "documentation/modules/ROOT/pages/extensions/pre-interrupt-callback.adoc",
"content": "= Pre-Interrupt Callback\n\n`{PreInterruptCallback}` defines the API for `Extensions` that wish to react on\ntimeouts before the `Thread.interrupt()` is called.\n\nPlease refer to xref:writing-tests/timeouts.adoc#debugging[Debugging Timeouts] for additional information.\n"
},
{
"path": "documentation/modules/ROOT/pages/extensions/providing-invocation-contexts-for-class-templates.adoc",
"content": "= Providing Invocation Contexts for Class Templates\n\nA `{ClassTemplate}` class can only be executed when at least one\n`{ClassTemplateInvocationContextProvider}` is registered. Each such provider is\nresponsible for providing a `Stream` of `{ClassTemplateInvocationContext}` instances.\nEach context may specify a custom display name and a list of additional extensions that\nwill only be used for the next invocation of the `{ClassTemplate}`.\n\nThe following example shows how to write a class template as well as how to register\nand implement a `{ClassTemplateInvocationContextProvider}`.\n\n[source,java,indent=0]\n.A class template with accompanying extension\n----\ninclude::example$java/example/ClassTemplateDemo.java[tags=user_guide]\n----\n\nIn this example, the class template will be invoked twice, meaning all test methods in\nthe class template will be executed twice. The display names of the invocations will be\n`apple` and `banana` as specified by the invocation context. Each invocation registers a\ncustom `{TestInstancePostProcessor}` which is used to inject a value into a field. The\noutput when using the `ConsoleLauncher` is as follows.\n\n....\n└─ ClassTemplateDemo ✔\n ├─ apple ✔\n │ ├─ notNull() ✔\n │ └─ wellKnown() ✔\n └─ banana ✔\n ├─ notNull() ✔\n └─ wellKnown() ✔\n....\n\nThe `{ClassTemplateInvocationContextProvider}` extension API is primarily intended for\nimplementing different kinds of tests that rely on repetitive invocation of _all_ test\nmethods in a test class albeit in different contexts — for example, with different\nparameters, by preparing the test class instance differently, or multiple times without\nmodifying the context.\nPlease refer to the implementations of\nxref:writing-tests/parameterized-classes-and-tests.adoc[Parameterized Classes] which uses this extension\npoint to provide its functionality.\n"
},
{
"path": "documentation/modules/ROOT/pages/extensions/providing-invocation-contexts-for-test-templates.adoc",
"content": "= Providing Invocation Contexts for Test Templates\n\nA `{TestTemplate}` method can only be executed when at least one\n`{TestTemplateInvocationContextProvider}` is registered. Each such provider is responsible\nfor providing a `Stream` of `{TestTemplateInvocationContext}` instances. Each context may\nspecify a custom display name and a list of additional extensions that will only be used\nfor the next invocation of the `{TestTemplate}` method.\n\nThe following example shows how to write a test template as well as how to register and\nimplement a `{TestTemplateInvocationContextProvider}`.\n\n[source,java,indent=0]\n.A test template with accompanying extension\n----\ninclude::example$java/example/TestTemplateDemo.java[tags=user_guide]\n----\n\nIn this example, the test template will be invoked twice. The display names of the\ninvocations will be `apple` and `banana` as specified by the invocation context. Each\ninvocation registers a custom `{ParameterResolver}` which is used to resolve the method\nparameter. The output when using the `ConsoleLauncher` is as follows.\n\n....\n└─ testTemplate(String) ✔\n ├─ apple ✔\n └─ banana ✔\n....\n\nThe `{TestTemplateInvocationContextProvider}` extension API is primarily intended for\nimplementing different kinds of tests that rely on repetitive invocation of a test-like\nmethod albeit in different contexts — for example, with different parameters, by preparing\nthe test class instance differently, or multiple times without modifying the context.\nPlease refer to the implementations of xref:writing-tests/repeated-tests.adoc[] or\nxref:writing-tests/parameterized-classes-and-tests.adoc[Parameterized Tests] which use this extension point\nto provide their functionality.\n"
},
{
"path": "documentation/modules/ROOT/pages/extensions/registering-extensions.adoc",
"content": "= Registering Extensions\n\nExtensions can be registered _declaratively_ via\n<>, _programmatically_ via\n<>, or _automatically_ via\nJava's <> mechanism.\n\n[[registration-declarative]]\n== Declarative Extension Registration\n\nDevelopers can register one or more extensions _declaratively_ by annotating a test\ninterface, test class, test method, or custom _xref:writing-tests/annotations.adoc#annotations[composed\nannotation]_ with `@ExtendWith(...)` and supplying class references for the extensions to\nregister. `@ExtendWith` may also be declared on fields or on parameters in test class\nconstructors, in test methods, and in `@BeforeAll`, `@AfterAll`, `@BeforeEach`, and\n`@AfterEach` lifecycle methods.\n\nFor example, to register a `WebServerExtension` for a particular test method, you would\nannotate the test method as follows. We assume the `WebServerExtension` starts a local web\nserver and injects the server's URL into parameters annotated with `@WebServerUrl`.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\n@Test\n@ExtendWith(WebServerExtension.class)\nvoid getProductList(@WebServerUrl String serverUrl) {\n\tWebClient webClient = new WebClient();\n\t// Use WebClient to connect to web server using serverUrl and verify response\n\tassertEquals(200, webClient.get(serverUrl + \"/products\").getResponseStatus());\n}\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\n@Test\n@ExtendWith(WebServerExtension::class)\nfun getProductList(@WebServerUrl serverUrl: String) {\n val webClient = WebClient()\n // Use WebClient to connect to web server using serverUrl and verify response\n assertEquals(200, webClient.get(\"$serverUrl/products\").responseStatus)\n}\n----\n--\n====\n\nTo register the `WebServerExtension` for all tests in a particular class and its\nsubclasses, you would annotate the test class as follows.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\n@ExtendWith(WebServerExtension.class)\nclass MyTests {\n\t// ...\n}\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\n@ExtendWith(WebServerExtension::class)\nclass MyTests {\n // ...\n}\n----\n--\n====\n\nMultiple extensions can be registered together like this:\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\n@ExtendWith({ DatabaseExtension.class, WebServerExtension.class })\nclass MyFirstTests {\n\t// ...\n}\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\n@ExtendWith(DatabaseExtension::class, WebServerExtension::class)\nclass MyFirstTests {\n // ...\n}\n----\n--\n====\n\nAs an alternative, multiple extensions can be registered separately like this:\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\n@ExtendWith(DatabaseExtension.class)\n@ExtendWith(WebServerExtension.class)\nclass MySecondTests {\n\t// ...\n}\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\n@ExtendWith(DatabaseExtension::class)\n@ExtendWith(WebServerExtension::class)\nclass MySecondTests {\n // ...\n}\n----\n--\n====\n\n[TIP]\n.Extension Registration Order\n====\nExtensions registered declaratively via `@ExtendWith` at the class level, method level, or\nparameter level will be executed in the order in which they are declared in the source\ncode. For example, the execution of tests in both `MyFirstTests` and `MySecondTests` will\nbe extended by the `DatabaseExtension` and `WebServerExtension`, **in exactly that order**.\n====\n\nIf you wish to combine multiple extensions in a reusable way, you can define a custom\n_xref:writing-tests/annotations.adoc#annotations[composed annotation]_ and use `@ExtendWith` as a\n_meta-annotation_ as in the following code listing. Then `@DatabaseAndWebServerExtension`\ncan be used in place of `@ExtendWith({ DatabaseExtension.class, WebServerExtension.class })`.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\n@Target({ ElementType.TYPE, ElementType.METHOD })\n@Retention(RetentionPolicy.RUNTIME)\n@ExtendWith({ DatabaseExtension.class, WebServerExtension.class })\npublic @interface DatabaseAndWebServerExtension {\n}\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\n@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)\n@Retention(AnnotationRetention.RUNTIME)\n@ExtendWith(DatabaseExtension::class, WebServerExtension::class)\nannotation class DatabaseAndWebServerExtension\n----\n--\n====\n\nThe above examples demonstrate how `@ExtendWith` can be applied at the class level or at\nthe method level; however, for certain use cases it makes sense for an extension to be\nregistered declaratively at the field or parameter level. Consider a\n`RandomNumberExtension` which generates random numbers that can be injected into a field or\nvia a parameter in a constructor, test method, or lifecycle method. If the extension\nprovides a `@Random` annotation that is meta-annotated with\n`@ExtendWith(RandomNumberExtension.class)` (see listing below), the extension can be used\ntransparently as in the following `RandomNumberDemo` example.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/extensions/Random.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/extensions/Random.kt[tags=user_guide]\n----\n--\n====\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/extensions/RandomNumberDemo.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/extensions/RandomNumberDemo.kt[tags=user_guide]\n----\n--\n====\n\n[[RandomNumberExtension]]\nThe following code listing provides an example of how one might choose to implement such a\n`RandomNumberExtension`. This implementation works for the use cases in\n`RandomNumberDemo`; however, it may not prove robust enough to cover all use cases -- for\nexample, the random number generation support is limited to integers; it uses\n`java.util.Random` instead of `java.security.SecureRandom`; etc. In any case, it is\nimportant to note which extension APIs are implemented and for what reasons.\n\nSpecifically, `RandomNumberExtension` implements the following extension APIs:\n\n- `BeforeAllCallback`: to support static field injection\n- `TestInstancePostProcessor`: to support non-static field injection\n- `ParameterResolver`: to support constructor and method injection\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/extensions/RandomNumberExtension.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/extensions/RandomNumberExtension.kt[tags=user_guide]\n----\n--\n====\n\n[TIP]\n.Extension Registration Order for `@ExtendWith` on Fields\n====\nExtensions registered declaratively via `@ExtendWith` on fields will be ordered relative\nto `@RegisterExtension` fields and other `@ExtendWith` fields using an algorithm that is\ndeterministic but intentionally nonobvious. However, `@ExtendWith` fields can be ordered\nusing the `@Order` annotation. See the <> tip for `@RegisterExtension` fields for details.\n====\n\n[TIP]\n.Extension Inheritance\n====\nExtensions registered declaratively via `@ExtendWith` on fields in superclasses will be\ninherited.\n\nSee <> for details.\n====\n\nNOTE: `@ExtendWith` fields may be either `static` or non-static. The documentation on\n<> and\n<> for\n`@RegisterExtension` fields also applies to `@ExtendWith` fields.\n\n[[registration-programmatic]]\n== Programmatic Extension Registration\n\nDevelopers can register extensions _programmatically_ by annotating fields in test classes\nwith `{RegisterExtension}`.\n\nWhen an extension is registered _declaratively_ via\n<>, it can typically only be configured\nvia annotations. In contrast, when an extension is registered via `@RegisterExtension`, it\ncan be configured _programmatically_ -- for example, in order to pass arguments to the\nextension's constructor, a static factory method, or a builder API.\n\n[[registration-programmatic-order]]\n[TIP]\n.Extension Registration Order\n====\nBy default, extensions registered programmatically via `@RegisterExtension` or\ndeclaratively via `@ExtendWith` on fields will be ordered using an algorithm that is\ndeterministic but intentionally nonobvious. This ensures that subsequent runs of a test\nsuite execute extensions in the same order, thereby allowing for repeatable builds.\nHowever, there are times when extensions need to be registered in an explicit order. To\nachieve that, annotate `@RegisterExtension` fields or `@ExtendWith` fields with `{Order}`.\n\nAny `@RegisterExtension` field or `@ExtendWith` field not annotated with `@Order` will be\nordered using the _default_ order which has a value of `Integer.MAX_VALUE / 2`. This\nallows `@Order` annotated extension fields to be explicitly ordered before or after\nnon-annotated extension fields. Extensions with an explicit order value less than the\ndefault order value will be registered before non-annotated extensions. Similarly,\nextensions with an explicit order value greater than the default order value will be\nregistered after non-annotated extensions. For example, assigning an extension an explicit\norder value that is greater than the default order value allows _before_ callback\nextensions to be registered last and _after_ callback extensions to be registered first,\nrelative to other programmatically registered extensions.\n====\n\n[TIP]\n.Extension Inheritance\n====\nExtensions registered via `@RegisterExtension` or `@ExtendWith` on fields in superclasses\nwill be inherited.\n\nSee <> for details.\n====\n\nNOTE: `@RegisterExtension` fields must not be `null` (at evaluation time) but may be\neither `static` or non-static.\n\n[[registration-programmatic-static-fields]]\n=== Static Fields\n\nIf a `@RegisterExtension` field is `static`, the extension will be registered after\nextensions that are registered at the class level via `@ExtendWith`. Such _static\nextensions_ are not limited in which extension APIs they can implement. Extensions\nregistered via static fields may therefore implement class-level and instance-level\nextension APIs such as `BeforeAllCallback`, `AfterAllCallback`,\n`TestInstancePostProcessor`, and `TestInstancePreDestroyCallback` as well as method-level\nextension APIs such as `BeforeEachCallback`, etc.\n\nIn the following example, the `server` field in the test class is initialized\nprogrammatically by using a builder pattern supported by the `WebServerExtension`. The\nconfigured `WebServerExtension` will be automatically registered as an extension at the\nclass level -- for example, in order to start the server before all tests in the class\nand then stop the server after all tests in the class have completed. In addition, static\nlifecycle methods annotated with `@BeforeAll` or `@AfterAll` as well as `@BeforeEach`,\n`@AfterEach`, and `@Test` methods can access the instance of the extension via the\n`server` field if necessary.\n\n[source,java,indent=0]\n.Registering an extension via a static field in Java\n----\ninclude::example$java/example/registration/WebServerDemo.java[tags=user_guide]\n----\n\n[[registration-programmatic-static-fields-kotlin]]\n==== Static Fields in Kotlin\n\nThe Kotlin programming language does not have the concept of a `static` field. However,\nthe compiler can be instructed to generate a `private static` field using the `@JvmStatic`\nannotation in Kotlin. If you want the Kotlin compiler to generate a `public static` field,\nyou can use the `@JvmField` annotation instead.\n\nThe following example is a version of the `WebServerDemo` from the previous section that\nhas been ported to Kotlin.\n\n[source,kotlin,indent=0]\n.Registering an extension via a static field in Kotlin\n----\ninclude::example$kotlin/example/registration/KotlinWebServerDemo.kt[tags=user_guide]\n----\n\n[[registration-programmatic-instance-fields]]\n=== Instance Fields\n\nIf a `@RegisterExtension` field is non-static (i.e., an instance field), the extension\nwill be registered after the test class has been instantiated and after each registered\n`TestInstancePostProcessor` has been given a chance to post-process the test instance\n(potentially injecting the instance of the extension to be used into the annotated\nfield). Thus, if such an _instance extension_ implements class-level or instance-level\nextension APIs such as `BeforeAllCallback`, `AfterAllCallback`, or\n`TestInstancePostProcessor`, those APIs will not be honored. Instance extensions will be\nregistered _before_ extensions that are registered at the method level via `@ExtendWith`.\n\nIn the following example, the `docs` field in the test class is initialized\nprogrammatically by invoking a custom `lookUpDocsDir()` method and supplying the result\nto the static `forPath()` factory method in the `DocumentationExtension`. The configured\n`DocumentationExtension` will be automatically registered as an extension at the method\nlevel. In addition, `@BeforeEach`, `@AfterEach`, and `@Test` methods can access the\ninstance of the extension via the `docs` field if necessary.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n.An extension registered via an instance field\n----\ninclude::example$java/example/registration/DocumentationDemo.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n.An extension registered via an instance field\n----\ninclude::example$kotlin/example/kotlin/registration/DocumentationDemo.kt[tags=user_guide]\n----\n--\n====\n\n[[registration-automatic]]\n== Automatic Extension Registration\n\nIn addition to <>\nand <> support\nusing annotations, JUnit Jupiter also supports _global extension registration_ via Java's\n`{ServiceLoader}` mechanism, allowing third-party extensions to be auto-detected and\nautomatically registered based on what is available in the classpath.\n\nSpecifically, a custom extension can be registered by supplying its fully qualified class\nname in a file named `org.junit.jupiter.api.extension.Extension` within the\n`/META-INF/services` folder in its enclosing JAR file.\n\n[[registration-automatic-enabling]]\n=== Enabling Automatic Extension Detection\n\nAuto-detection is an advanced feature and is therefore not enabled by default. To enable\nit, set the `junit.jupiter.extensions.autodetection.enabled` _configuration parameter_ to\n`true`. This can be supplied as a JVM system property, as a _configuration parameter_ in\nthe `LauncherDiscoveryRequest` that is passed to the `Launcher`, or via the JUnit Platform\nconfiguration file (see xref:running-tests/configuration-parameters.adoc[] for details).\n\nFor example, to enable auto-detection of extensions, you can start your JVM with the\nfollowing system property.\n\n`-Djunit.jupiter.extensions.autodetection.enabled=true`\n\nWhen auto-detection is enabled, extensions discovered via the `{ServiceLoader}` mechanism\nwill be added to the extension registry after JUnit Jupiter's global extensions (e.g.,\nsupport for `TestInfo`, `TestReporter`, etc.).\n\n[[registration-automatic-filtering]]\n=== Filtering Auto-detected Extensions\n\nThe list of auto-detected extensions can be filtered using include and exclude patterns\nvia the following xref:running-tests/configuration-parameters.adoc[configuration parameters]:\n\n`junit.jupiter.extensions.autodetection.include=`::\n Comma-separated list of _include_ patterns for auto-detected extensions.\n`junit.jupiter.extensions.autodetection.exclude=`::\n Comma-separated list of _exclude_ patterns for auto-detected extensions.\n\nInclude patterns are applied _before_ exclude patterns. If both include and exclude\npatterns are provided, only extensions that match at least one include pattern and do not\nmatch any exclude pattern will be auto-detected.\n\nSee xref:running-tests/configuration-parameters.adoc#pattern[Pattern Matching Syntax] for details on the pattern syntax.\n\n[[registration-inheritance]]\n== Extension Inheritance\n\nRegistered extensions are inherited within test class hierarchies with top-down semantics.\nSimilarly, extensions registered at the class-level are inherited at the method-level.\nThis applies to all extensions, independent of how they are registered (declaratively or\nprogrammatically).\n\nThis means that extensions registered declaratively via `@ExtendWith` on a superclass will\nbe registered before extensions registered declaratively via `@ExtendWith` on a subclass.\n\nSimilarly, extensions registered programmatically via `@RegisterExtension` or\n`@ExtendWith` on fields in a superclass will be registered before extensions registered\nprogrammatically via `@RegisterExtension` or `@ExtendWith` on fields in a subclass, unless\n`@Order` is used to alter that behavior (see <> for details).\n\nNOTE: A specific extension implementation can only be registered once for a given\nextension context and its parent contexts. Consequently, any attempt to register a\nduplicate extension implementation will be ignored.\n"
},
{
"path": "documentation/modules/ROOT/pages/extensions/relative-execution-order-of-user-code-and-extensions.adoc",
"content": "= Relative Execution Order of User Code and Extensions\n\nWhen executing a test class that contains one or more test methods, a number of extension\ncallbacks are called in addition to the user-supplied test and lifecycle methods.\n\nNOTE: See also: xref:writing-tests/test-execution-order.adoc[]\n\n[[overview]]\n== User and Extension Code\n\nThe following diagram illustrates the relative order of user-supplied code and extension\ncode. User-supplied test and lifecycle methods are shown in orange, with callback code\nimplemented by extensions shown in blue. The grey box denotes the execution of a single\ntest method and will be repeated for every test method in the test class.\n\n[[diagram]]\n.User code and extension code\nimage::extensions_lifecycle.png[]\n\nThe following table further explains the sixteen steps in the\n<> diagram.\n\n. *interface* `*org.junit.jupiter.api.extension.BeforeAllCallback*` +\nextension code executed before all tests of the container are executed\n. *annotation* `*org.junit.jupiter.api.BeforeAll*` +\nuser code executed before all tests of the container are executed\n. *interface* `*org.junit.jupiter.api.extension.LifecycleMethodExecutionExceptionHandler\n#handleBeforeAllMethodExecutionException*` +\nextension code for handling exceptions thrown from `@BeforeAll` methods\n. *interface* `*org.junit.jupiter.api.extension.BeforeClassTemplateInvocationCallback*` +\nextension code executed before each class template invocation is executed (only applicable\nif the test class is a xref:writing-tests/class-templates.adoc[class template])\n. *interface* `*org.junit.jupiter.api.extension.BeforeEachCallback*` +\nextension code executed before each test is executed\n. *annotation* `*org.junit.jupiter.api.BeforeEach*` +\nuser code executed before each test is executed\n. *interface* `*org.junit.jupiter.api.extension.LifecycleMethodExecutionExceptionHandler\n#handleBeforeEachMethodExecutionException*` +\nextension code for handling exceptions thrown from `@BeforeEach` methods\n. *interface* `*org.junit.jupiter.api.extension.BeforeTestExecutionCallback*` +\nextension code executed immediately before a test is executed\n. *annotation* `*org.junit.jupiter.api.Test*` +\nuser code of the actual test method\n. *interface* `*org.junit.jupiter.api.extension.TestExecutionExceptionHandler*` +\nextension code for handling exceptions thrown during a test\n. *interface* `*org.junit.jupiter.api.extension.AfterTestExecutionCallback*` +\nextension code executed immediately after test execution and its corresponding exception handlers\n. *annotation* `*org.junit.jupiter.api.AfterEach*` +\nuser code executed after each test is executed\n. *interface* `*org.junit.jupiter.api.extension.LifecycleMethodExecutionExceptionHandler\n#handleAfterEachMethodExecutionException*` +\nextension code for handling exceptions thrown from `@AfterEach` methods\n. *interface* `*org.junit.jupiter.api.extension.AfterEachCallback*` +\nextension code executed after each test is executed\n. *interface* `*org.junit.jupiter.api.extension.AfterClassTemplateInvocationCallback*` +\nextension code executed after each class template invocation is executed (only applicable\nif the test class is a xref:writing-tests/class-templates.adoc[class template])\n. *annotation* `*org.junit.jupiter.api.AfterAll*` +\nuser code executed after all tests of the container are executed\n. *interface* `*org.junit.jupiter.api.extension.LifecycleMethodExecutionExceptionHandler\n#handleAfterAllMethodExecutionException*` +\nextension code for handling exceptions thrown from `@AfterAll` methods\n. *interface* `*org.junit.jupiter.api.extension.AfterAllCallback*` +\nextension code executed after all tests of the container are executed\n\nIn the simplest case only the actual test method will be executed (step 9); all other\nsteps are optional depending on the presence of user code or extension support for the\ncorresponding lifecycle callback. For further details on the various lifecycle callbacks\nplease consult the respective Javadoc for each annotation and extension.\n\nAll invocations of user code methods in the above table can additionally be intercepted\nby implementing xref:extensions/intercepting-invocations.adoc[`InvocationInterceptor`].\n\n[[wrapping-behavior]]\n== Wrapping Behavior of Callbacks\n\nJUnit Jupiter always guarantees _wrapping_ behavior for multiple registered extensions\nthat implement lifecycle callbacks such as `BeforeAllCallback`, `AfterAllCallback`,\n`BeforeClassTemplateInvocationCallback`, `AfterClassTemplateInvocationCallback`,\n`BeforeEachCallback`, `AfterEachCallback`, `BeforeTestExecutionCallback`, and\n`AfterTestExecutionCallback`.\n\nThat means that, given two extensions `Extension1` and `Extension2` with `Extension1`\nregistered before `Extension2`, any \"before\" callbacks implemented by `Extension1` are\nguaranteed to execute **before** any \"before\" callbacks implemented by `Extension2`.\nSimilarly, given the two same two extensions registered in the same order, any \"after\"\ncallbacks implemented by `Extension1` are guaranteed to execute **after** any \"after\"\ncallbacks implemented by `Extension2`. `Extension1` is therefore said to _wrap_\n`Extension2`.\n\nJUnit Jupiter also guarantees _wrapping_ behavior within class and interface hierarchies\nfor user-supplied _lifecycle methods_ (see xref:writing-tests/definitions.adoc[]).\n\n* `@BeforeAll` methods are inherited from superclasses as long as they are not\n _overridden_. Furthermore, `@BeforeAll` methods from superclasses will be executed\n **before** `@BeforeAll` methods in subclasses.\n** Similarly, `@BeforeAll` methods declared in an interface are inherited as long as they\n are not _overridden_, and `@BeforeAll` methods from an interface will be executed\n **before** `@BeforeAll` methods in the class that implements the interface.\n* `@AfterAll` methods are inherited from superclasses as long as they are not\n _overridden_. Furthermore, `@AfterAll` methods from superclasses will be executed\n **after** `@AfterAll` methods in subclasses.\n** Similarly, `@AfterAll` methods declared in an interface are inherited as long as they\n are not _overridden_, and `@AfterAll` methods from an interface will be executed\n **after** `@AfterAll` methods in the class that implements the interface.\n* `@BeforeEach` methods are inherited from superclasses as long as they are not\n _overridden_. Furthermore, `@BeforeEach` methods from superclasses will be executed\n **before** `@BeforeEach` methods in subclasses.\n** Similarly, `@BeforeEach` methods declared as interface default methods are inherited as\n long as they are not _overridden_, and `@BeforeEach` default methods will be executed\n **before** `@BeforeEach` methods in the class that implements the interface.\n* `@AfterEach` methods are inherited from superclasses as long as they are not\n _overridden_. Furthermore, `@AfterEach` methods from superclasses will be executed\n **after** `@AfterEach` methods in subclasses.\n** Similarly, `@AfterEach` methods declared as interface default methods are inherited as\n long as they are not _overridden_, and `@AfterEach` default methods will be executed\n **after** `@AfterEach` methods in the class that implements the interface.\n\nThe following examples demonstrate this behavior. Please note that the examples do not\nactually do anything realistic. Instead, they mimic common scenarios for testing\ninteractions with the database. All methods imported statically from the `Logger` class\nlog contextual information in order to help us better understand the execution order of\nuser-supplied callback methods and callback methods in extensions.\n\n[source,java,indent=0]\n.Extension1\n----\ninclude::example$java/example/callbacks/Extension1.java[tags=user_guide]\n----\n\n[source,java,indent=0]\n.Extension2\n----\ninclude::example$java/example/callbacks/Extension2.java[tags=user_guide]\n----\n\n[source,java,indent=0]\n.AbstractDatabaseTests\n----\ninclude::example$java/example/callbacks/AbstractDatabaseTests.java[tags=user_guide]\n----\n\n[source,java,indent=0]\n.DatabaseTestsDemo\n----\ninclude::example$java/example/callbacks/DatabaseTestsDemo.java[tags=user_guide]\n----\n\nWhen the `DatabaseTestsDemo` test class is executed, the following is logged.\n\n----\n@BeforeAll AbstractDatabaseTests.createDatabase()\n@BeforeAll DatabaseTestsDemo.beforeAll()\n Extension1.beforeEach()\n Extension2.beforeEach()\n @BeforeEach AbstractDatabaseTests.connectToDatabase()\n @BeforeEach DatabaseTestsDemo.insertTestDataIntoDatabase()\n @Test DatabaseTestsDemo.testDatabaseFunctionality()\n @AfterEach DatabaseTestsDemo.deleteTestDataFromDatabase()\n @AfterEach AbstractDatabaseTests.disconnectFromDatabase()\n Extension2.afterEach()\n Extension1.afterEach()\n@BeforeAll DatabaseTestsDemo.afterAll()\n@AfterAll AbstractDatabaseTests.destroyDatabase()\n----\n\nThe following sequence diagram helps to shed further light on what actually goes on within\nthe `JupiterTestEngine` when the `DatabaseTestsDemo` test class is executed.\n\n////\nPNG generated using ZenUML: https://app.zenuml.com\n\nSee corresponding *.txt file in images folder for the source.\n////\nimage::extensions_DatabaseTestsDemo.png[caption='',title='DatabaseTestsDemo']\n\nJUnit Jupiter does **not** guarantee the execution order of multiple lifecycle methods\nthat are declared within a _single_ test class or test interface. It may at times appear\nthat JUnit Jupiter invokes such methods in alphabetical order. However, that is not\nprecisely true. The ordering is analogous to the ordering for `@Test` methods within a\nsingle test class.\n\n[NOTE]\n====\nLifecycle methods that are declared within a _single_ test class or test interface will be\nordered using an algorithm that is deterministic but intentionally non-obvious. This\nensures that subsequent runs of a test suite execute lifecycle methods in the same order,\nthereby allowing for repeatable builds.\n====\n\nIn addition, JUnit Jupiter does **not** support _wrapping_ behavior for multiple lifecycle\nmethods declared within a single test class or test interface.\n\nThe following example demonstrates this behavior. Specifically, the lifecycle method\nconfiguration is _broken_ due to the order in which the locally declared lifecycle methods\nare executed.\n\n* Test data is inserted _before_ the database connection has been opened, which results in\n a failure to connect to the database.\n* The database connection is closed _before_ deleting the test data, which results in a\n failure to connect to the database.\n\n[source,java,indent=0]\n.BrokenLifecycleMethodConfigDemo\n----\ninclude::example$java/example/callbacks/BrokenLifecycleMethodConfigDemo.java[tags=user_guide]\n----\n\nWhen the `BrokenLifecycleMethodConfigDemo` test class is executed, the following is logged.\n\n----\nExtension1.beforeEach()\nExtension2.beforeEach()\n @BeforeEach BrokenLifecycleMethodConfigDemo.insertTestDataIntoDatabase()\n @BeforeEach BrokenLifecycleMethodConfigDemo.connectToDatabase()\n @Test BrokenLifecycleMethodConfigDemo.testDatabaseFunctionality()\n @AfterEach BrokenLifecycleMethodConfigDemo.disconnectFromDatabase()\n @AfterEach BrokenLifecycleMethodConfigDemo.deleteTestDataFromDatabase()\nExtension2.afterEach()\nExtension1.afterEach()\n----\n\nThe following sequence diagram helps to shed further light on what actually goes on within\nthe `JupiterTestEngine` when the `BrokenLifecycleMethodConfigDemo` test class is executed.\n\n////\nPNG generated using ZenUML: https://app.zenuml.com\n\nSee corresponding *.txt file in images folder for the source.\n////\nimage::extensions_BrokenLifecycleMethodConfigDemo.png[caption='',title='BrokenLifecycleMethodConfigDemo']\n\n[TIP]\n====\nDue to the aforementioned behavior, the JUnit Team recommends that developers declare at\nmost one of each type of _lifecycle method_ (see xref:writing-tests/definitions.adoc[]) per test\nclass or test interface unless there are no dependencies between such lifecycle methods.\n====\n"
},
{
"path": "documentation/modules/ROOT/pages/extensions/supported-utilities-in-extensions.adoc",
"content": "= Supported Utilities in Extensions\n\nThe `junit-platform-commons` artifact provides _maintained_ utilities for working with\nannotations, classes, reflection, classpath scanning, and conversion tasks. These\nutilities can be found in the `{junit-platform-support-package}` and its subpackages.\n`TestEngine` and `Extension` authors are encouraged to use these supported utilities in\norder to align with the behavior of the JUnit Platform and JUnit Jupiter.\n\n[[annotations]]\n== Annotation Support\n\n`AnnotationSupport` provides static utility methods that operate on annotated elements\n(e.g., packages, annotations, classes, interfaces, constructors, methods, and fields).\nThese include methods to check whether an element is annotated or meta-annotated with a\nparticular annotation, to search for specific annotations, and to find annotated methods\nand fields in a class or interface. Some of these methods search on implemented\ninterfaces and within class hierarchies to find annotations. Consult the Javadoc for\n`{AnnotationSupport}` for further details.\n\nNOTE: The `isAnnotated()` methods do not find repeatable annotations. To check for repeatable annotations,\nuse one of the `findRepeatableAnnotations()` methods and verify that the returned list is not empty.\n\nNOTE: See also: <>\n\n[[classes]]\n== Class Support\n\n`ClassSupport` provides static utility methods for working with classes (i.e., instances\nof `java.lang.Class`). Consult the Javadoc for `{ClassSupport}` for further details.\n\n[[reflection]]\n== Reflection Support\n\n`ReflectionSupport` provides static utility methods that augment the standard JDK\nreflection and class-loading mechanisms. These include methods to scan the classpath in\nsearch of classes matching specified predicates, to load and create new instances of a\nclass, and to find and invoke methods. Some of these methods traverse class hierarchies\nto locate matching methods. Consult the Javadoc for `{ReflectionSupport}` for further\ndetails.\n\nNOTE: See also: <>\n\n[[modifier]]\n== Modifier Support\n\n`ModifierSupport` provides static utility methods for working with member and class\nmodifiers -- for example, to determine if a member is declared as `public`, `private`,\n`abstract`, `static`, etc. Consult the Javadoc for `{ModifierSupport}` for further\ndetails.\n\n[[conversion]]\n== Conversion Support\n\n`ConversionSupport` (in the `org.junit.platform.commons.support.conversion` package)\nprovides support for converting from strings to primitive types and their corresponding\nwrapper types, date and time types from the `java.time package`, and some additional\ncommon Java types such as `File`, `BigDecimal`, `BigInteger`, `Currency`, `Locale`, `URI`,\n`URL`, `UUID`, etc. Consult the Javadoc for `{ConversionSupport}` for further details.\n\n[[search-semantics]]\n== Field and Method Search Semantics\n\nVarious methods in `AnnotationSupport` and `ReflectionSupport` use search algorithms that\ntraverse type hierarchies to locate matching fields and methods – for example,\n`AnnotationSupport.findAnnotatedFields(...)`, `ReflectionSupport.findMethods(...)`, etc.\n\nThe field and method search algorithms adhere to standard Java semantics regarding whether\na given field or method is visible or overridden according to the rules of the Java\nlanguage.\n"
},
{
"path": "documentation/modules/ROOT/pages/extensions/test-instance-factories.adoc",
"content": "= Test Instance Factories\n\n`{TestInstanceFactory}` defines the API for `Extensions` that wish to _create_ test class\ninstances.\n\nCommon use cases include acquiring the test instance from a dependency injection\nframework or invoking a static factory method to create the test class instance.\n\nIf no `TestInstanceFactory` is registered, the framework will invoke the _sole_\nconstructor for the test class to instantiate it, potentially resolving constructor\narguments via registered `ParameterResolver` extensions.\n\nExtensions that implement `TestInstanceFactory` can be registered on test interfaces,\ntop-level test classes, or `@Nested` test classes.\n\n[WARNING]\n====\nRegistering multiple extensions that implement `TestInstanceFactory` for any single class\nwill result in an exception being thrown for all tests in that class, in any subclass,\nand in any nested class. Note that any `TestInstanceFactory` registered in a superclass\nor _enclosing_ class (i.e., in the case of a `@Nested` test class) is _inherited_. It is\nthe user's responsibility to ensure that only a single `TestInstanceFactory` is\nregistered for any specific test class.\n====\n\n[NOTE]\n.Accessing the test-scoped `ExtensionContext`\n====\nYou may override the `getTestInstantiationExtensionContextScope(...)` method to return\n`TEST_METHOD` to make test-specific data available to your extension implementation or if\nyou want to xref:extensions/keeping-state-in-extensions.adoc[keep state] on the test method level.\n====\n"
},
{
"path": "documentation/modules/ROOT/pages/extensions/test-instance-post-processing.adoc",
"content": "= Test Instance Post-processing\n\n`{TestInstancePostProcessor}` defines the API for `Extensions` that wish to _post\nprocess_ test instances.\n\nCommon use cases include injecting dependencies into the test instance, invoking custom\ninitialization methods on the test instance, etc.\n\nFor a concrete example, consult the source code for the `{MockitoExtension}` and the\n`{SpringExtension}`.\n\n[NOTE]\n.Accessing the test-scoped `ExtensionContext`\n====\nYou may override the `getTestInstantiationExtensionContextScope(...)` method to return\n`TEST_METHOD` to make test-specific data available to your extension implementation or if\nyou want to xref:extensions/keeping-state-in-extensions.adoc[keep state] on the test method level.\n====\n"
},
{
"path": "documentation/modules/ROOT/pages/extensions/test-instance-pre-construct-callback.adoc",
"content": "= Test Instance Pre-construct Callback\n\n`{TestInstancePreConstructCallback}` defines the API for `Extensions` that wish to be invoked\n_prior_ to test instances being constructed (by a constructor call or via\n`{TestInstanceFactory}`).\n\nThis extension provides a symmetric call to `{TestInstancePreDestroyCallback}` and is useful\nin combination with other extensions to prepare constructor parameters or keeping track of test\ninstances and their lifecycle.\n\n[NOTE]\n.Accessing the test-scoped `ExtensionContext`\n====\nYou may override the `getTestInstantiationExtensionContextScope(...)` method to return\n`TEST_METHOD` to make test-specific data available to your extension implementation or if\nyou want to xref:extensions/keeping-state-in-extensions.adoc[keep state] on the test method level.\n====\n"
},
{
"path": "documentation/modules/ROOT/pages/extensions/test-instance-pre-destroy-callback.adoc",
"content": "= Test Instance Pre-destroy Callback\n\n`{TestInstancePreDestroyCallback}` defines the API for `Extensions` that wish to process\ntest instances _after_ they have been used in tests and _before_ they are destroyed.\n\nCommon use cases include cleaning dependencies that have been injected into the\ntest instance, invoking custom de-initialization methods on the test instance, etc.\n"
},
{
"path": "documentation/modules/ROOT/pages/extensions/test-lifecycle-callbacks.adoc",
"content": "= Test Lifecycle Callbacks\n\nThe following interfaces define the APIs for extending tests at various points in the\ntest execution lifecycle. Consult the following sections for examples and the Javadoc for\neach of these interfaces in the `{extension-api-package}` package for further details.\n\n* `{BeforeAllCallback}`\n** `{BeforeClassTemplateInvocationCallback}` (only applicable for\n xref:writing-tests/class-templates.adoc[class templates])\n*** `{BeforeEachCallback}`\n**** `{BeforeTestExecutionCallback}`\n**** `{AfterTestExecutionCallback}`\n*** `{AfterEachCallback}`\n** `{AfterClassTemplateInvocationCallback}` (only applicable for\n xref:writing-tests/class-templates.adoc[class templates])\n* `{AfterAllCallback}`\n\n.Implementing Multiple Extension APIs\nNOTE: Extension developers may choose to implement any number of these interfaces\nwithin a single extension. Consult the source code of the `{SpringExtension}` for a\nconcrete example.\n\n[[before-after-execution]]\n== Before and After Test Execution Callbacks\n\n`{BeforeTestExecutionCallback}` and `{AfterTestExecutionCallback}` define the APIs for\n`Extensions` that wish to add behavior that will be executed _immediately before_ and\n_immediately after_ a test method is executed, respectively. As such, these callbacks are\nwell suited for timing, tracing, and similar use cases. If you need to implement\ncallbacks that are invoked _around_ `@BeforeEach` and `@AfterEach` methods, implement\n`BeforeEachCallback` and `AfterEachCallback` instead.\n\nThe following example shows how to use these callbacks to calculate and log the execution\ntime of a test method. `TimingExtension` implements both `BeforeTestExecutionCallback`\nand `AfterTestExecutionCallback` in order to time and log the test execution.\n\n[[timing-extension]]\n.An extension that times and logs the execution of test methods\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/timing/TimingExtension.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/timing/TimingExtension.kt[tags=user_guide]\n----\n--\n====\n\nSince the `TimingExtensionTests` class registers the `TimingExtension` via `@ExtendWith`,\nits tests will have this timing applied when they execute.\n\n.A test class that uses the example TimingExtension\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/timing/TimingExtensionTests.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/timing/TimingExtensionTests.kt[tags=user_guide]\n----\n--\n====\n\nThe following is an example of the logging produced when `TimingExtensionTests` is run.\n\n....\nINFO: Method [sleep20ms] took 24 ms.\nINFO: Method [sleep50ms] took 53 ms.\n....\n"
},
{
"path": "documentation/modules/ROOT/pages/extensions/test-result-processing.adoc",
"content": "= Test Result Processing\n\n`{TestWatcher}` defines the API for extensions that wish to process the results of _test\nmethod_ executions. Specifically, a `TestWatcher` will be invoked with contextual\ninformation for the following events.\n\n* `testDisabled`: invoked after a disabled _test method_ has been skipped\n* `testSuccessful`: invoked after a _test method_ has completed successfully\n* `testAborted`: invoked after a _test method_ has been aborted\n* `testFailed`: invoked after a _test method_ has failed\n\nNOTE: In contrast to the definition of \"test method\" presented in\nxref:writing-tests/definitions.adoc[], in this context _test method_ refers to any `@Test` method\nor `@TestTemplate` method (for example, a `@RepeatedTest` or `@ParameterizedTest`).\n\nExtensions implementing this interface can be registered at the class level, instance\nlevel, or method level. When registered at the class level, a `TestWatcher` will be\ninvoked for any contained _test method_ including those in `@Nested` classes. When\nregistered at the method level, a `TestWatcher` will only be invoked for the _test method_\nfor which it was registered.\n\n[WARNING]\n====\nIf a `TestWatcher` is registered via a non-static (instance) field – for example, using\n`@RegisterExtension` – and the test class is configured with\n`@TestInstance(Lifecycle.PER_METHOD)` semantics (which is the default lifecycle mode), the\n`TestWatcher` will **not** be invoked with events for `@TestTemplate` methods (for\nexample, `@RepeatedTest` or `@ParameterizedTest`).\n\nTo ensure that a `TestWatcher` is invoked for all _test methods_ in a given class, it is\ntherefore recommended that the `TestWatcher` be registered at the class level with\n`@ExtendWith` or via a `static` field with `@RegisterExtension` or `@ExtendWith`.\n====\n\nIf there is a failure at the class level — for example, an exception thrown by a\n`@BeforeAll` method — no test results will be reported. Similarly, if the test class is\ndisabled via an `ExecutionCondition` — for example, `@Disabled` — no test results will be\nreported.\n\nIn contrast to other Extension APIs, a `TestWatcher` is not permitted to adversely\ninfluence the execution of tests. Consequently, any exception thrown by a method in the\n`TestWatcher` API will be logged at `WARNING` level and will not be allowed to propagate\nor fail test execution.\n\n[WARNING]\n====\nAny instances of `ExtensionContext.Store.CloseableResource` stored in the `Store` of the\nprovided `{ExtensionContext}` will be closed _before_ methods in the `TestWatcher` API are\ninvoked (see xref:extensions/keeping-state-in-extensions.adoc[]). You can use the parent context's `Store` to\nwork with such resources.\n====\n"
},
{
"path": "documentation/modules/ROOT/pages/migrating-from-junit4.adoc",
"content": "= Migrating from JUnit 4\n\nAlthough the JUnit Jupiter programming model and extension model do not support JUnit 4\nfeatures such as `Rules` and `Runners` natively, it is not expected that source code\nmaintainers will need to update all of their existing tests, test extensions, and custom\nbuild test infrastructure to migrate to JUnit Jupiter.\n\nInstead, JUnit provides a gentle migration path via a _JUnit Vintage test engine_ which\nallows existing tests based on JUnit 3 and JUnit 4 to be executed using the JUnit Platform\ninfrastructure. Since all classes and annotations specific to JUnit Jupiter reside under\nthe `org.junit.jupiter` base package, having both JUnit 4 and JUnit Jupiter in the\nclasspath does not lead to any conflicts. It is therefore safe to maintain existing JUnit\n4 tests alongside JUnit Jupiter tests and migrate them gradually.\n\n\n[[running]]\n== Running JUnit 4 Tests on the JUnit Platform\n\n[WARNING]\n====\nThe JUnit Vintage engine is deprecated and should only be used temporarily while\nmigrating tests to JUnit Jupiter or another testing framework with native JUnit Platform\nsupport.\n\nBy default, if the JUnit Vintage engine is registered and discovers at least one test\nclass, it reports a xref:running-tests/discovery-issues.adoc[discovery issue] of INFO severity.\nYou can prevent this discovery issue from being reported by setting the\n`junit.vintage.discovery.issue.reporting.enabled`\nxref:running-tests/configuration-parameters.adoc[configuration parameter] to `false`.\n====\n\nMake sure that the `junit-vintage-engine` artifact is in your test runtime path. In that\ncase JUnit 3 and JUnit 4 tests will automatically be picked up by the JUnit Platform\nlauncher.\n\nSee the example projects in the {junit-examples-repo}[`junit-examples`] repository to\nfind out how this is done with Gradle and Maven.\n\n[[categories-support]]\n=== Categories Support\n\nFor test classes or methods that are annotated with `@Category`, the _JUnit Vintage test\nengine_ exposes the category's fully qualified class name as a xref:running-tests/tags.adoc[tag]\nfor the corresponding test class or test method. For example, if a test method is\nannotated with `@Category(Example.class)`, it will be tagged with `\"com.acme.Example\"`.\nSimilar to the `Categories` runner in JUnit 4, this information can be used to filter the\ndiscovered tests before executing them (see xref:running-tests/intro.adoc[] for details).\n\n[[parallel-execution]]\n== Parallel Execution\n\nThe JUnit Vintage test engine supports parallel execution of top-level test classes and test methods,\nallowing existing JUnit 3 and JUnit 4 tests to benefit from improved performance through\nconcurrent test execution. It can be enabled and configured using the following\nxref:running-tests/configuration-parameters.adoc[configuration parameters]:\n\n`junit.vintage.execution.parallel.enabled=true|false`::\n Enable/disable parallel execution (defaults to `false`). Requires opt-in for `classes`\n or `methods` to be executed in parallel using the configuration parameters below.\n\n`junit.vintage.execution.parallel.classes=true|false`::\n Enable/disable parallel execution of test classes (defaults to `false`).\n\n`junit.vintage.execution.parallel.methods=true|false`::\n Enable/disable parallel execution of test methods (defaults to `false`).\n\n`junit.vintage.execution.parallel.pool-size=`::\n Specifies the size of the thread pool to be used for parallel execution. By default, the\n number of available processors is used.\n\n[[parallel-execution-class-level]]\n=== Parallelization at Class Level\n\nLet's assume we have two test classes `FooTest` and `BarTest` with each class containing\nthree unit tests. Now, let's enable parallel execution of test classes:\n\n[source,properties]\n----\njunit.vintage.execution.parallel.enabled=true\njunit.vintage.execution.parallel.classes=true\n----\n\nWith this setup, the `VintageTestEngine` will use two different threads,\none for each test class:\n\n[source,plaintext]\n----\nForkJoinPool-1-worker-1 - BarTest::test1\nForkJoinPool-1-worker-2 - FooTest::test1\nForkJoinPool-1-worker-1 - BarTest::test2\nForkJoinPool-1-worker-2 - FooTest::test2\nForkJoinPool-1-worker-1 - BarTest::test3\nForkJoinPool-1-worker-2 - FooTest::test3\n----\n\n[[parallel-execution-method-level]]\n=== Parallelization at Method Level\n\nAlternatively, we can enable parallel test execution at a method level,\nrather than the class level:\n\n[source,properties]\n----\njunit.vintage.execution.parallel.enabled=true\njunit.vintage.execution.parallel.methods=true\n----\n\nTherefore, the test methods within each class will be executed in parallel, while\ndifferent test classes will be executed sequentially:\n\n[source,plaintext]\n----\nForkJoinPool-1-worker-1 - BarTest::test1\nForkJoinPool-1-worker-2 - BarTest::test2\nForkJoinPool-1-worker-3 - BarTest::test3\n\nForkJoinPool-1-worker-3 - FooTest::test1\nForkJoinPool-1-worker-2 - FooTest::test2\nForkJoinPool-1-worker-1 - FooTest::test3\n----\n\n[[parallel-execution-class-and-method-level]]\n=== Full Parallelization\n\nFinally, we can also enable parallelization at both class and method level:\n\n[source,properties]\n----\njunit.vintage.execution.parallel.enabled=true\njunit.vintage.execution.parallel.classes=true\njunit.vintage.execution.parallel.methods=true\n----\n\nWith these properties set, the `VintageTestEngine` will execute all tests classes and\nmethods in parallel, potentially significantly reducing the overall test suite execution time:\n\n[source,plaintext]\n----\nForkJoinPool-1-worker-6 - FooTest::test2\nForkJoinPool-1-worker-7 - BarTest::test3\nForkJoinPool-1-worker-3 - FooTest::test1\nForkJoinPool-1-worker-8 - FooTest::test3\nForkJoinPool-1-worker-5 - BarTest::test2\nForkJoinPool-1-worker-4 - BarTest::test1\n----\n\n[[parallel-execution-pool-size]]\n=== Configuring the Pool Size\n\nThe default thread pool size is equal to the number of available processors. However, we\ncan also configure the pool size explicitly:\n\n[source,properties]\n----\njunit.vintage.execution.parallel.enabled=true\njunit.vintage.execution.parallel.classes=true\njunit.vintage.execution.parallel.methods=true\njunit.vintage.execution.parallel.pool-size=4\n----\n\nFor instance, if we update our previous example that uses full parallelization and\nconfigure the pool size to four, we can expect to see our six test methods executed with\na parallelism of four:\n\n[source,plaintext]\n----\nForkJoinPool-1-worker-2 - FooTest::test1\nForkJoinPool-1-worker-4 - BarTest::test2\nForkJoinPool-1-worker-3 - BarTest::test1\nForkJoinPool-1-worker-4 - BarTest::test3\nForkJoinPool-1-worker-2 - FooTest::test2\nForkJoinPool-1-worker-3 - FooTest::test3\n----\n\nAs we can see, even though we set the thread pool size was four, only three threads were\nused in this case. This happens because the pool adjusts the number of active threads\nbased on workload and system needs.\n\n[[parallel-execution-disabled]]\n=== Sequential Execution\n\nOn the other hand, if we disable parallel execution, the `VintageTestEngine`\nwill execute all tests sequentially, regardless of the other properties:\n\n[source,properties]\n----\njunit.vintage.execution.parallel.enabled=false\njunit.vintage.execution.parallel.classes=true\njunit.vintage.execution.parallel.methods=true\n----\n\nSimilarly, tests will be executed sequentially if you enable parallel execution in general\nbut enable neither class-level nor method-level parallelization.\n\n[[tips]]\n== Migration Tips\n\nThe following are topics that you should be aware of when migrating existing JUnit 4\ntests to JUnit Jupiter.\n\n* Annotations reside in the `org.junit.jupiter.api` package.\n* Assertions reside in `org.junit.jupiter.api.Assertions`.\n - Note that you may continue to use assertion methods from `org.junit.Assert` or any\n other assertion library such as {AssertJ}, {Hamcrest}, {Truth}, etc.\n* Assumptions reside in `org.junit.jupiter.api.Assumptions`.\n - Note that JUnit Jupiter supports methods from JUnit 4's `org.junit.Assume` class for\n assumptions. Specifically, JUnit Jupiter supports JUnit 4's\n `AssumptionViolatedException` to signal that a test should be aborted instead of\n marked as a failure.\n* `@Before` and `@After` no longer exist; use `@BeforeEach` and `@AfterEach` instead.\n* `@BeforeClass` and `@AfterClass` no longer exist; use `@BeforeAll` and `@AfterAll`\n instead.\n* `@Ignore` no longer exists: use `@Disabled` or one of the other built-in\n xref:writing-tests/conditional-test-execution.adoc[execution conditions] instead\n - See also <>.\n* `@Category` no longer exists; use `@Tag` instead.\n* `@RunWith` no longer exists; superseded by `@ExtendWith`.\n - For `@RunWith(Enclosed.class)` use `@Nested`.\n - For `@RunWith(Parameterized.class)` see <>.\n* `@Rule` and `@ClassRule` no longer exist; superseded by `@ExtendWith` and\n `@RegisterExtension`.\n - See also <>.\n* `@Test(expected = ...)` and the `ExpectedException` rule no longer exist; use\n `Assertions.assertThrows(...)` instead.\n - See <> if you still need to use\n `ExpectedException`.\n* Assertions and assumptions in JUnit Jupiter accept the failure message as their last\n argument instead of the first one.\n - See <> for details.\n\n[[tips-parameterized]]\n=== Parameterized test classes\n\nUnless `@UseParametersRunnerFactory` is used, a JUnit 4 parameterized test class can be\nconverted into a JUnit Jupiter\nxref:writing-tests/parameterized-classes-and-tests.adoc[`@ParameterizedClass`] by following these steps:\n\n. Replace `@RunWith(Parameterized.class)` with `@ParameterizedClass`.\n. Add a class-level `@MethodSource(\"methodName\")` annotation where `methodName` is the\n name of the method annotated with `@Parameters` and remove the `@Parameters` annotation\n from the method.\n. Replace `@BeforeParam` and `@AfterParam` with `@BeforeParameterizedClassInvocation` and\n `@AfterParameterizedClassInvocation`, respectively, if there are any methods with such\n annotations.\n. Change the imports of the `@Test` and `@Parameter` annotations to use the\n `org.junit.jupiter.params` package.\n. Change assertions etc. to use the `org.junit.jupiter.api` package as usual.\n. Optionally, remove all `public` modifiers from the class and its methods and fields.\n\n====\n[source,java,indent=0]\n.Before\n----\ninclude::example$java/example/ParameterizedMigrationDemo.java[tags=before]\n----\n\n[source,java,indent=0]\n.After\n----\ninclude::example$java/example/ParameterizedMigrationDemo.java[tags=after]\n----\n====\n\n[[rule-support]]\n== Limited JUnit 4 Rule Support\n\nWARNING: _JUnit 4 rule support_ is deprecated for removal since version 6.0.0. Please\nmigrate to the corresponding APIs and extensions provided by JUnit Jupiter.\n\nAs stated above, JUnit Jupiter does not and will not support JUnit 4 rules natively. The\nJUnit team realizes, however, that many organizations, especially large ones, are likely\nto have large JUnit 4 code bases that make use of custom rules. To serve these\norganizations and enable a gradual migration path the JUnit team has decided to support a\nselection of JUnit 4 rules verbatim within JUnit Jupiter. This support is based on\nadapters and is limited to those rules that are semantically compatible to the JUnit\nJupiter extension model, i.e. those that do not completely change the overall execution\nflow of the test.\n\nThe `junit-jupiter-migrationsupport` module from JUnit Jupiter currently supports the\nfollowing three `Rule` types including subclasses of these types:\n\n* `org.junit.rules.ExternalResource` (including `org.junit.rules.TemporaryFolder`)\n* `org.junit.rules.Verifier` (including `org.junit.rules.ErrorCollector`)\n* `org.junit.rules.ExpectedException`\n\nAs in JUnit 4, Rule-annotated fields as well as methods are supported. By using these\nclass-level extensions on a test class such `Rule` implementations in legacy code bases\ncan be _left unchanged_ including the JUnit 4 rule import statements.\n\nThis limited form of `Rule` support can be switched on by the class-level annotation\n`{EnableRuleMigrationSupport}`. This annotation is a _composed annotation_ which enables\nall rule migration support extensions: `VerifierSupport`, `ExternalResourceSupport`, and\n`ExpectedExceptionSupport`. You may alternatively choose to annotate your test class with\n`@EnableJUnit4MigrationSupport` which registers migration support for rules _and_ JUnit\n4's `@Ignore` annotation (see <>).\n\nHowever, if you intend to develop a new extension for JUnit Jupiter please use the new\nextension model of JUnit Jupiter instead of the rule-based model of JUnit 4.\n\n\n[[ignore-annotation-support]]\n== JUnit 4 @Ignore Support\n\nWARNING: _JUnit 4 `@Ignore` support_ is deprecated for removal since version 6.0.0. Please\nuse JUnit Jupiter's `@Disabled` annotation instead.\n\nIn order to provide a smooth migration path from JUnit 4 to JUnit Jupiter, the\n`junit-jupiter-migrationsupport` module provides support for JUnit 4's `@Ignore`\nannotation analogous to Jupiter's `{Disabled}` annotation.\n\nTo use `@Ignore` with JUnit Jupiter based tests, configure a _test_ dependency on the\n`junit-jupiter-migrationsupport` module in your build and then annotate your test class\nwith `@ExtendWith(IgnoreCondition.class)` or `{EnableJUnit4MigrationSupport}` (which\nautomatically registers the `IgnoreCondition` along with\n<>). The `IgnoreCondition` is an\n`{ExecutionCondition}` that disables test classes or test methods that are annotated with\n`@Ignore`.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/IgnoredTestsDemo.java[tags=user_guide]\n----\n\n\n[[failure-message-arguments]]\n== Failure Message Arguments\n\nThe `Assumptions` and `Assertions` classes in JUnit Jupiter declare arguments in a\ndifferent order than in JUnit 4. In JUnit 4 assertion and assumption methods accept the\nfailure message as the first argument; whereas, in JUnit Jupiter assertion and assumption\nmethods accept the failure message as the last argument.\n\nFor instance, the method `assertEquals` in JUnit 4 is declared as `assertEquals(String\nmessage, Object expected, Object actual)`, but in JUnit Jupiter it is declared as\n`assertEquals(Object expected, Object actual, String message)`. The rationale for this is\nthat a failure message is _optional_, and optional arguments should be declared after\nrequired arguments in a method signature.\n\nThe methods affected by this change are the following:\n\n- Assertions\n * `assertTrue`\n * `assertFalse`\n * `assertNull`\n * `assertNotNull`\n * `assertEquals`\n * `assertNotEquals`\n * `assertArrayEquals`\n * `assertSame`\n * `assertNotSame`\n * `assertThrows`\n- Assumptions\n * `assumeTrue`\n * `assumeFalse`\n"
},
{
"path": "documentation/modules/ROOT/pages/overview.adoc",
"content": "= Overview\n:page-aliases: index.adoc, user-guide/index.adoc\n\nThe goal of this document is to provide comprehensive reference documentation for\nprogrammers writing tests, extension authors, and engine authors as well as build tool\nand IDE vendors.\n\n[[what-is-junit]]\n== What is JUnit?\n\nJUnit is composed of several different modules from three different sub-projects.\n\n[.text-center]\n**JUnit {version} = _JUnit Platform_ + _JUnit Jupiter_ + _JUnit Vintage_**\n\nThe **JUnit Platform** serves as a foundation for\nxref:advanced-topics/launcher-api.adoc[launching testing frameworks] on the JVM. It also\ndefines the `{TestEngine}` API for developing a testing framework that runs on the\nplatform. Furthermore, the platform provides a\nxref:running-tests/console-launcher.adoc[Console Launcher] to launch the platform from the\ncommand line and the xref:advanced-topics/junit-platform-suite-engine.adoc[] for running a\ncustom test suite using one or more test engines on the platform. First-class support for\nthe JUnit Platform also exists in popular IDEs (see\nxref:running-tests/ide-support.adoc#intellij-idea[IntelliJ IDEA],\nxref:running-tests/ide-support.adoc#eclipse[Eclipse],\nxref:running-tests/ide-support.adoc#netbeans[NetBeans], and\nxref:running-tests/ide-support.adoc#vscode[Visual Studio Code]) and build tools (see\nxref:running-tests/build-support.adoc#gradle[Gradle],\nxref:running-tests/build-support.adoc#maven[Maven],\nxref:running-tests/build-support.adoc#ant[Ant],\nxref:running-tests/build-support.adoc#bazel[Bazel], and\nxref:running-tests/build-support.adoc#sbt[sbt]).\n\n**JUnit Jupiter** is the combination of the xref:writing-tests/intro.adoc[programming model] and\nxref:extensions/overview.adoc[extension model] for writing JUnit tests and extensions. The Jupiter\nsub-project provides a `TestEngine` for running Jupiter based tests on the platform.\n\n**JUnit Vintage** provides a `TestEngine` for running JUnit 3 and JUnit 4 based tests on\nthe platform. It requires JUnit 4.12 or later to be present on the class path or module\npath. Note, however, that the JUnit Vintage engine is deprecated and should only be used\ntemporarily while migrating tests to JUnit Jupiter or another testing framework with\nnative JUnit Platform support.\n\n[[java-versions]]\n== Supported Java Versions\n\nJUnit requires Java 17 (or higher) at runtime. However, you can still test code that\nhas been compiled with previous versions of the JDK.\n\n[[getting-help]]\n== Getting Help\n\nAsk JUnit-related questions on {StackOverflow} or use the {DiscussionsQA}[Q&A category on GitHub Discussions].\n\n[[getting-started]]\n== Getting Started\n\n[[getting-started-junit-artifacts]]\n=== Downloading JUnit Artifacts\n\nTo find out what artifacts are available for download and inclusion in your project, refer\nto xref:appendix.adoc#dependency-metadata[Dependency Metadata]. To set up dependency management for your build, refer to\nxref:running-tests/build-support.adoc[] and the <>.\n\n[[getting-started-features]]\n=== JUnit Features\n\nTo find out what features are available in JUnit {version} and how to use them, read the\ncorresponding sections of this User Guide, organized by topic.\n\n* xref:writing-tests/intro.adoc[Writing Tests in JUnit Jupiter]\n* xref:migrating-from-junit4.adoc[Migrating from JUnit 4 to JUnit Jupiter]\n* xref:running-tests/intro.adoc[]\n* xref:extensions/overview.adoc[Extension Model for JUnit Jupiter]\n* Advanced Topics\n - xref:advanced-topics/launcher-api.adoc[]\n - xref:advanced-topics/testkit.adoc[]\n\n[[getting-started-example-projects]]\n=== Example Projects\n\nTo see complete, working examples of projects that you can copy and experiment with, the\n{junit-examples-repo}[`junit-examples`] repository is a good place to start. The\n`junit-examples` repository hosts a collection of example projects based on JUnit Jupiter,\nJUnit Vintage, and other testing frameworks. You'll find appropriate build scripts (e.g.,\n`build.gradle`, `pom.xml`, etc.) in the example projects. The links below highlight some\nof the combinations you can choose from.\n\n* For Gradle and Java, check out the `{junit-jupiter-starter-gradle}` project.\n* For Gradle and Kotlin, check out the `{junit-jupiter-starter-gradle-kotlin}` project.\n* For Gradle and Groovy, check out the `{junit-jupiter-starter-gradle-groovy}` project.\n* For Maven, check out the `{junit-jupiter-starter-maven}` project.\n* For Ant, check out the `{junit-jupiter-starter-ant}` project.\n* For Bazel, check out the `{junit-jupiter-starter-bazel}` project.\n* For sbt, check out the `{junit-jupiter-starter-sbt}` project.\n"
},
{
"path": "documentation/modules/ROOT/pages/release-notes.adoc",
"content": "= Release Notes\n:page-aliases: release-notes/index.adoc\n//\n//\n\nThis document contains the change log for all JUnit releases since 6.0 GA.\n\ninclude::partial$release-notes/release-notes-6.1.0.adoc[]\n\ninclude::partial$release-notes/release-notes-6.1.0-RC1.adoc[]\n\ninclude::partial$release-notes/release-notes-6.1.0-M1.adoc[]\n\ninclude::partial$release-notes/release-notes-6.0.3.adoc[]\n\ninclude::partial$release-notes/release-notes-6.0.2.adoc[]\n\ninclude::partial$release-notes/release-notes-6.0.1.adoc[]\n\ninclude::partial$release-notes/release-notes-6.0.0.adoc[]\n"
},
{
"path": "documentation/modules/ROOT/pages/running-tests/build-support.adoc",
"content": "= Build Support\n\n[[gradle]]\n== Gradle\n\nStarting with https://docs.gradle.org/4.6/release-notes.html[version 4.6], Gradle provides\nhttps://docs.gradle.org/current/userguide/java_testing.html#using_junit5[native support]\nfor executing tests on the JUnit Platform. To enable it, you need to specify\n`useJUnitPlatform()` within a `test` task declaration in `build.gradle`:\n\n[source,groovy,indent=0]\n[subs=attributes+]\n----\ntest {\n\tuseJUnitPlatform()\n}\n----\n\nFiltering by xref:running-tests/tags.adoc[tags],\nxref:running-tests/tags.adoc#expressions[tag expressions], or engines is also supported:\n\n[source,groovy,indent=0]\n[subs=attributes+]\n----\ntest {\n\tuseJUnitPlatform {\n\t\tincludeTags(\"fast\", \"smoke & feature-a\")\n\t\t// excludeTags(\"slow\", \"ci\")\n\t\tincludeEngines(\"junit-jupiter\")\n\t\t// excludeEngines(\"junit-vintage\")\n\t}\n}\n----\n\nPlease refer to the\nhttps://docs.gradle.org/current/userguide/java_testing.html[official Gradle documentation]\nfor a comprehensive list of options.\n\n[[gradle-bom]]\n=== Aligning dependency versions\n\nTIP: See <> for details on how to override the version\nof JUnit used in your Spring Boot application.\n\nUnless you're using Spring Boot which defines its own way of managing dependencies, it is\nrecommended to use the JUnit Platform xref:appendix.adoc#dependency-metadata-junit-bom[Bill of Materials (BOM)] to align the\nversions of all JUnit artifacts.\n\n[source,groovy,indent=0]\n[subs=attributes+]\n.Explicit platform dependency on the BOM\n----\ndependencies {\n\ttestImplementation(platform(\"org.junit:junit-bom:{version}\"))\n\ttestImplementation(\"org.junit.jupiter:junit-jupiter\")\n\ttestRuntimeOnly(\"org.junit.platform:junit-platform-launcher\")\n}\n----\n\nUsing the BOM allows you to omit the version when declaring dependencies on all artifacts\nwith the `org.junit.platform`, `org.junit.jupiter`, and `org.junit.vintage` group IDs.\n\nSince all JUnit artifacts declare a\nhttps://docs.gradle.org/current/userguide/platforms.html[platform] dependency on the BOM,\nyou usually don't need to declare an explicit dependency on it yourself. Instead, it's\nsufficient to declare _one_ regular dependency that includes a version number. Gradle will\nthen pull in the BOM automatically so you can omit the version for all other JUnit\nartifacts.\n\n[source,groovy,indent=0]\n[subs=attributes+]\n.Implicit platform dependency on the BOM\n----\ndependencies {\n\ttestImplementation(\"org.junit.jupiter:junit-jupiter:{version}\") // <1>\n\ttestRuntimeOnly(\"org.junit.platform:junit-platform-launcher\") // <2>\n}\n----\n<1> Dependency declaration with explicit version. Pulls in the `junit-bom` automatically.\n<2> Dependency declaration without version. The version is supplied by the `junit-bom`.\n\n[WARNING]\n.Declaring a dependency on junit-platform-launcher\n====\nEven though pre-8.0 versions of Gradle don't require declaring an explicit\ndependency on `junit-platform-launcher`, it is recommended to do so to ensure the versions\nof JUnit artifacts on the test runtime classpath are aligned.\n\nMoreover, doing so is recommended and in some cases even required when importing the\nproject into an IDE like xref:running-tests/ide-support.adoc#eclipse[Eclipse] or\nxref:running-tests/ide-support.adoc#intellij-idea[IntelliJ IDEA].\n====\n\n[[gradle-engines-configure]]\n=== Configuring Test Engines\n\nIn order to run any tests at all, a `TestEngine` implementation must be on the classpath.\n\nTo configure support for JUnit Jupiter based tests, configure a `testImplementation` dependency\non the dependency-aggregating JUnit Jupiter artifact similar to the following.\n\n[source,groovy,indent=0]\n[subs=attributes+]\n----\ndependencies {\n\ttestImplementation(\"org.junit.jupiter:junit-jupiter:{version}\")\n\ttestRuntimeOnly(\"org.junit.platform:junit-platform-launcher\")\n}\n----\n\nAlternatively, you can use Gradle's\nhttps://docs.gradle.org/current/userguide/jvm_test_suite_plugin.html[JVM Test Suite]\nsupport.\n\n[source,kotlin,indent=0]\n[subs=attributes+]\n.Kotlin DSL\n----\ntesting {\n\tsuites {\n\t\tnamed(\"test\") {\n\t\t\tuseJUnitJupiter(\"{version}\")\n\t\t}\n\t}\n}\n----\n\n[source,groovy,indent=0]\n[subs=attributes+]\n.Groovy DSL\n----\ntesting {\n\tsuites {\n\t\ttest {\n\t\t\tuseJUnitJupiter(\"{version}\")\n\t\t}\n\t}\n}\n----\n\nThe JUnit Platform can run JUnit 4 based tests as long as you configure a `testImplementation`\ndependency on JUnit 4 and a `testRuntimeOnly` dependency on the JUnit Vintage `TestEngine`\nimplementation similar to the following.\n\n[source,groovy,indent=0]\n[subs=attributes+]\n----\ndependencies {\n\ttestImplementation(\"junit:junit:{junit4-version}\")\n\ttestRuntimeOnly(\"org.junit.vintage:junit-vintage-engine:{version}\")\n\ttestRuntimeOnly(\"org.junit.platform:junit-platform-launcher\")\n}\n----\n\n[[gradle-config-params]]\n=== Configuration Parameters\n\nThe standard Gradle `test` task currently does not provide a dedicated DSL to set JUnit\nPlatform xref:running-tests/configuration-parameters.adoc[configuration parameters] to influence test\ndiscovery and execution. However, you can provide configuration parameters within the\nbuild script via system properties (as shown below) or via the\n`junit-platform.properties` file.\n\n[source,groovy,indent=0]\n----\ntest {\n\t// ...\n\tsystemProperty(\"junit.jupiter.conditions.deactivate\", \"*\")\n\tsystemProperty(\"junit.jupiter.extensions.autodetection.enabled\", true)\n\tsystemProperty(\"junit.jupiter.testinstance.lifecycle.default\", \"per_class\")\n\t// ...\n}\n----\n\n[[gradle-logging]]\n=== Configuring Logging (optional)\n\nJUnit uses the Java Logging APIs in the `java.util.logging` package (a.k.a. _JUL_) to\nemit warnings and debug information. Please refer to the official documentation of\n`{LogManager}` for configuration options.\n\nAlternatively, it's possible to redirect log messages to other logging frameworks such as\n{Log4j} or {Logback}. To use a logging framework that provides a custom implementation of\n`{LogManager}`, set the `java.util.logging.manager` system property to the _fully\nqualified class name_ of the `{LogManager}` implementation to use. The example below\ndemonstrates how to configure Log4j{nbsp}2.x (see {Log4j_JDK_Logging_Adapter} for\ndetails).\n\n[source,groovy,indent=0]\n[subs=attributes+]\n----\ntest {\n\tsystemProperty(\"java.util.logging.manager\", \"org.apache.logging.log4j.jul.LogManager\")\n\t// Avoid overhead (see https://logging.apache.org/log4j/2.x/manual/jmx.html#enabling-jmx)\n\tsystemProperty(\"log4j2.disableJmx\", \"true\")\n}\n----\n\nOther logging frameworks provide different means to redirect messages logged using\n`java.util.logging`. For example, for {Logback} you can use the\nhttps://www.slf4j.org/legacy.html#jul-to-slf4j[JUL to SLF4J Bridge] by adding it as a\ndependency to the test runtime classpath.\n\n[[maven]]\n== Maven\n\nMaven Surefire and Maven Failsafe provide\nhttps://maven.apache.org/surefire/maven-surefire-plugin/examples/junit-platform.html[native support]\nfor executing tests on the JUnit Platform. The `pom.xml` file in the\n`{junit-jupiter-starter-maven}` project demonstrates how to use the Maven Surefire plugin\nand can serve as a starting point for configuring your Maven build.\n\n[WARNING]\n.Minimum required version of Maven Surefire/Failsafe\n====\nAs of JUnit 6.0, the minimum required version of Maven Surefire/Failsafe is 3.0.0.\n====\n\n[[maven-bom]]\n=== Aligning dependency versions\n\nUnless you're using Spring Boot which defines its own way of managing dependencies, it is\nrecommended to use the JUnit Platform xref:appendix.adoc#dependency-metadata-junit-bom[Bill of Materials (BOM)] to align the\nversions of all JUnit artifacts.\n\n[source,xml,indent=0]\n[subs=attributes+]\n----\n\n\t\n\t\t\n\t\t\torg.junit \n\t\t\tjunit-bom \n\t\t\t{version} \n\t\t\tpom \n\t\t\timport \n\t\t \n\t \n \n----\n\nUsing the BOM allows you to omit the version when declaring dependencies on all artifacts\nwith the `org.junit.platform`, `org.junit.jupiter`, and `org.junit.vintage` group IDs.\n\nTIP: See <> for details on how to override the version\nof JUnit used in your Spring Boot application.\n\n[[maven-engines-configure]]\n=== Configuring Test Engines\n\nIn order to have Maven Surefire or Maven Failsafe run any tests at all, at least one\n`TestEngine` implementation must be added to the test classpath.\n\nTo configure support for JUnit Jupiter based tests, configure `test` scoped dependencies\non the JUnit Jupiter API and the JUnit Jupiter `TestEngine` implementation similar to the\nfollowing.\n\n[source,xml,indent=0]\n[subs=attributes+]\n----\n\t\n\t\n\t\t\n\t\t\n\t\t\torg.junit.jupiter \n\t\t\tjunit-jupiter \n\t\t\t{version} \n\t\t\ttest \n\t\t \n\t\t\n\t \n\t\n\t\t\n\t\t\t\n\t\t\t\tmaven-surefire-plugin \n\t\t\t\t{surefire-version} \n\t\t\t \n\t\t\t\n\t\t\t\tmaven-failsafe-plugin \n\t\t\t\t{surefire-version} \n\t\t\t \n\t\t \n\t \n\t\n----\n\nMaven Surefire and Maven Failsafe can run JUnit 4 based tests alongside Jupiter tests as\nlong as you configure `test` scoped dependencies on JUnit 4 and the JUnit Vintage\n`TestEngine` implementation similar to the following.\n\n[source,xml,indent=0]\n[subs=attributes+]\n----\n\t\n\t\n\t\t\n\t\t\n\t\t\tjunit \n\t\t\tjunit \n\t\t\t{junit4-version} \n\t\t\ttest \n\t\t \n\t\t\n\t\t\torg.junit.vintage \n\t\t\tjunit-vintage-engine \n\t\t\t{version} \n\t\t\ttest \n\t\t \n\t\t\n\t \n\t\n\t\n\t\t\n\t\t\t\n\t\t\t\tmaven-surefire-plugin \n\t\t\t\t{surefire-version} \n\t\t\t \n\t\t\t\n\t\t\t\tmaven-failsafe-plugin \n\t\t\t\t{surefire-version} \n\t\t\t \n\t\t \n\t \n\t\n----\n\n[[maven-filter-test-class-names]]\n=== Filtering by Test Class Names\n\nThe Maven Surefire Plugin will scan for test classes whose fully qualified names match\nthe following patterns.\n\n- `+++**/Test*.java+++`\n- `+++**/*Test.java+++`\n- `+++**/*Tests.java+++`\n- `+++**/*TestCase.java+++`\n\nMoreover, it will exclude all nested classes (including static member classes) by default.\n\nNote, however, that you can override this default behavior by configuring explicit\n`include` and `exclude` rules in your `pom.xml` file. For example, to keep Maven Surefire\nfrom excluding static member classes, you can override its exclude rules as follows.\n\n[source,xml,indent=0]\n[subs=attributes+]\n.Overriding exclude rules of Maven Surefire\n----\n\t\n\t\n\t\t\n\t\t\t\n\t\t\t\tmaven-surefire-plugin \n\t\t\t\t{surefire-version} \n\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\t\t \n\t\t\t\t \n\t\t\t \n\t\t \n\t \n\t\n----\n\nPlease see the\nhttps://maven.apache.org/surefire/maven-surefire-plugin/examples/inclusion-exclusion.html[Inclusions and Exclusions of Tests]\ndocumentation for Maven Surefire for details.\n\n[[maven-filter-tags]]\n=== Filtering by Tags\n\nYou can filter tests by xref:running-tests/tags.adoc[tags] or\nxref:running-tests/tags.adoc#expressions[tag expressions] using the following configuration\nproperties.\n\n- to include _tags_ or _tag expressions_, use `groups`.\n- to exclude _tags_ or _tag expressions_, use `excludedGroups`.\n\n[source,xml,indent=0]\n[subs=attributes+]\n----\n\t\n\t\n\t\t\n\t\t\t\n\t\t\t\tmaven-surefire-plugin \n\t\t\t\t{surefire-version} \n\t\t\t\t\n\t\t\t\t\tacceptance | !feature-a \n\t\t\t\t\tintegration, regression \n\t\t\t\t \n\t\t\t \n\t\t \n\t \n\t\n----\n\n[[maven-config-params]]\n=== Configuration Parameters\n\nYou can set JUnit Platform xref:running-tests/configuration-parameters.adoc[configuration parameters] to\ninfluence test discovery and execution by declaring the `configurationParameters`\nproperty and providing key-value pairs using the Java `Properties` file syntax (as shown\nbelow) or via the `junit-platform.properties` file.\n\n[source,xml,indent=0]\n[subs=attributes+]\n----\n\t\n\t\n\t\t\n\t\t\t\n\t\t\t\tmaven-surefire-plugin \n\t\t\t\t{surefire-version} \n\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\tjunit.jupiter.conditions.deactivate = *\n\t\t\t\t\t\t\tjunit.jupiter.extensions.autodetection.enabled = true\n\t\t\t\t\t\t\tjunit.jupiter.testinstance.lifecycle.default = per_class\n\t\t\t\t\t\t \n\t\t\t\t\t \n\t\t\t\t \n\t\t\t \n\t\t \n\t \n\t\n----\n\n[[ant]]\n== Ant\n\nStarting with version `1.10.3`, link:https://ant.apache.org/[Ant] has a\nlink:https://ant.apache.org/manual/Tasks/junitlauncher.html[`junitlauncher`] task that\nprovides native support for launching tests on the JUnit Platform. The `junitlauncher`\ntask is solely responsible for launching the JUnit Platform and passing it the selected\ncollection of tests. The JUnit Platform then delegates to registered test engines to\ndiscover and execute the tests.\n\nThe `junitlauncher` task attempts to align as closely as possible with native Ant\nconstructs such as\nlink:https://ant.apache.org/manual/Types/resources.html#collection[resource collections]\nfor allowing users to select the tests that they want executed by test engines. This gives\nthe task a consistent and natural feel when compared to many other core Ant tasks.\n\nStarting with version `1.10.6` of Ant, the `junitlauncher` task supports\nlink:https://ant.apache.org/manual/Tasks/junitlauncher.html#fork[forking the tests in a separate JVM].\n\nThe `build.xml` file in the `{junit-jupiter-starter-ant}` project demonstrates how to use\nthe task and can serve as a starting point.\n\n=== Basic Usage\n\nThe following example demonstrates how to configure the `junitlauncher` task to select a\nsingle test class (i.e., `com.example.project.CalculatorTests`).\n\n[source,xml,indent=0]\n----\n\t\n\t\t\n\t\t \n\n\t\n\n\t\n\t\t \n----\n\nThe `test` element allows you to specify a single test class that you want to be selected\nand executed. The `classpath` element allows you to specify the classpath to be used to\nlaunch the JUnit Platform. This classpath will also be used to locate test classes that\nare part of the execution.\n\nThe following example demonstrates how to configure the `junitlauncher` task to select\ntest classes from multiple locations.\n\n[source,xml,indent=0]\n----\n\t\n\t\t\n\t\t \n\t\n\t\n\t\t\n\t\t\t\n\t\t\t\t \n\t\t\t\n\t\t\t\t \n\t\t \n\t \n----\n\nIn the above example, the `testclasses` element allows you to select multiple test\nclasses that reside in different locations.\n\nFor further details on usage and configuration options please refer to the official Ant\ndocumentation for the\nlink:https://ant.apache.org/manual/Tasks/junitlauncher.html[`junitlauncher` task].\n\n[[bazel]]\n== Bazel\n\nFor Bazel, add dependencies on\nhttps://github.com/bazel-contrib/rules_jvm_external[rules_jvm_external] and\nhttps://github.com/bazel-contrib/rules_jvm[contrib_rules_jvm] to your module's manifest\nand install JUnit's artifacts.\n\n[source,skylark]\n[subs=attributes+]\n.MODULE.bazel\n----\nbazel_dep(name = \"rules_jvm_external\", version = \"6.9\")\nbazel_dep(name = \"contrib_rules_jvm\", version = \"0.31.1\")\n\nmaven = use_extension(\"@rules_jvm_external//:extensions.bzl\", \"maven\")\n\nmaven.install(\n artifacts = [\n \"org.junit.jupiter:junit-jupiter-api:{version}\",\n \"org.junit.jupiter:junit-jupiter-params:{version}\",\n \"org.junit.jupiter:junit-jupiter-engine:{version}\",\n \"org.junit.platform:junit-platform-launcher:{version}\",\n \"org.junit.platform:junit-platform-reporting:{version}\",\n ],\n repositories = [\n \"https://repo1.maven.org/maven2\",\n ],\n)\n\nuse_repo(maven, \"maven\")\n----\n\nNext, in your `BUILD` file, define a `java_test_suite` for your tests.\n\n[source,skylark]\n[subs=attributes+]\n.BUILD\n----\nload(\"@rules_jvm_external//:defs.bzl\", \"artifact\")\nload(\"@contrib_rules_jvm//java:defs.bzl\", \"java_test_suite\")\n\njava_library(\n name = \"your-library-name\",\n srcs = glob([\"src/main/java/**/*.java\"]),\n)\n\njava_test_suite(\n name = \"your-library-name-tests\",\n size = \"small\",\n srcs = glob([\"src/test/java/**/*.java\"]),\n runner = \"junit5\",\n test_suffixes = [\"Test.java\", \"Tests.java\"],\n runtime_deps = runtime_deps = [\n artifact(\"org.junit.jupiter:junit-jupiter-engine\"),\n artifact(\"org.junit.platform:junit-platform-launcher\"),\n artifact(\"org.junit.platform:junit-platform-reporting\"),\n ],\n deps = [\n \":your-library-name\",\n artifact(\"org.junit.jupiter:junit-jupiter-api\"),\n artifact(\"org.junit.jupiter:junit-jupiter-params\"),\n ],\n)\n----\n\nTo execute your tests, run `bazel test //...`. For a full example, please check out the\n`{junit-jupiter-starter-bazel}` example project.\n\n[[sbt]]\n== sbt\n\nFor sbt, you first need to declare a dependency on the\nhttps://github.com/sbt/sbt-jupiter-interface[sbt-jupiter-interface] plugin. Despite its\nname, it supports running any class-based JUnit Platform test engine.\n\n[source,scala]\n.project/plugins.sbt\n----\naddSbtPlugin(\"com.github.sbt.junit\" % \"sbt-jupiter-interface\" % \"0.17.0\")\n----\n\nIn your build definition, add dependencies on the corresponding `jupiter-interface` along\nJUnit's artifacts. Moreover, you should configure the `jupiterTestFramework` and its\nhttps://github.com/sbt/sbt-jupiter-interface#framework-options[options].\n\n[source,scala]\n[subs=attributes+]\n.build.sbt\n----\nlazy val root = project\n .in(file(\".\"))\n .settings(\n name := \"junit-jupiter-starter-sbt\",\n libraryDependencies ++= Seq(\n \"com.github.sbt.junit\" % \"jupiter-interface\" % JupiterKeys.jupiterVersion.value % Test,\n \"org.junit.jupiter\" % \"junit-jupiter\" % \"{version}\" % Test,\n \"org.junit.platform\" % \"junit-platform-launcher\" % \"{version}\" % Test,\n ),\n testOptions += Tests.Argument(jupiterTestFramework, \"--display-mode=tree\")\n )\n----\n\nFinally, execute your tests by running `sbt test`. For a full example, please check out\nthe `{junit-jupiter-starter-sbt}` example project.\n\n[[spring-boot]]\n== Spring Boot\n\nlink:https://spring.io/projects/spring-boot[Spring Boot] provides automatic support for\nmanaging the version of JUnit used in your project. In addition, the\n`spring-boot-starter-test` artifact automatically includes testing libraries such as JUnit\nJupiter, AssertJ, Mockito, etc.\n\nIf your build relies on dependency management support from Spring Boot, you should not\nimport JUnit's xref:appendix.adoc#dependency-metadata-junit-bom[Bill of Materials (BOM)] in your build script since that would\nresult in duplicate (and potentially conflicting) management of JUnit dependencies.\n\nIf you need to override the version of a dependency used in your Spring Boot application,\nyou have to override the exact name of the\nlink:https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#appendix.dependency-versions.properties[version property]\ndefined in the BOM used by the Spring Boot plugin. For example, the name of the JUnit\nJupiter version property in Spring Boot is `junit-jupiter.version`. The mechanism for\nchanging a dependency version is documented for both\nlink:https://docs.spring.io/spring-boot/docs/current/gradle-plugin/reference/htmlsingle/#managing-dependencies.dependency-management-plugin.customizing[Gradle]\nand\nlink:https://docs.spring.io/spring-boot/docs/current/maven-plugin/reference/htmlsingle/#using.parent-pom[Maven].\n\nWith Gradle you can override the JUnit Jupiter version by including the following in your\n`build.gradle` file.\n\n[source,groovy,indent=0]\n[subs=attributes+]\n----\n\text['junit-jupiter.version'] = '{version}'\n----\n\nWith Maven you can override the JUnit Jupiter version by including the following in your\n`pom.xml` file.\n\n[source,xml,indent=0]\n[subs=attributes+]\n----\n\t\n\t\t{version} \n\t \n----\n"
},
{
"path": "documentation/modules/ROOT/pages/running-tests/capturing-standard-output-error.adoc",
"content": "= Capturing Standard Output/Error\n\nThe JUnit Platform provides opt-in support for capturing output printed to `System.out`\nand `System.err`. To enable it, set the `junit.platform.output.capture.stdout` and/or\n`junit.platform.output.capture.stderr` xref:running-tests/configuration-parameters.adoc[configuration\nparameter] to `true`. In addition, you may configure the maximum number of buffered bytes\nto be used per executed test or container using `junit.platform.output.capture.maxBuffer`.\n\nIf enabled, the JUnit Platform captures the corresponding output and publishes it as a\nreport entry using the `stdout` or `stderr` keys to all registered\n`{TestExecutionListener}` instances immediately before reporting the test or container as\nfinished.\n\nPlease note that the captured output will only contain output emitted by the thread that\nwas used to execute a container or test. Any output by other threads will be omitted\nbecause particularly when\nxref:writing-tests/parallel-execution.adoc[executing tests in parallel] it would be impossible\nto attribute it to a specific test or container.\n"
},
{
"path": "documentation/modules/ROOT/pages/running-tests/configuration-parameters.adoc",
"content": "= Configuration Parameters\n\nIn addition to instructing the platform which test classes and test engines to include,\nwhich packages to scan, etc., it is sometimes necessary to provide additional custom\nconfiguration parameters that are specific to a particular test engine, listener, or\nregistered extension. For example, the JUnit Jupiter `TestEngine` supports _configuration\nparameters_ for the following use cases.\n\n- xref:writing-tests/test-instance-lifecycle.adoc#default[Changing the Default Test Instance Lifecycle]\n- xref:extensions/registering-extensions.adoc#registration-automatic-enabling[Enabling Automatic Extension Detection]\n- xref:extensions/conditional-test-execution.adoc#deactivation[Deactivating Conditions]\n- xref:writing-tests/display-names.adoc#generator-default[Setting the Default Display Name Generator]\n\n_Configuration Parameters_ are text-based key-value pairs that can be supplied to test\nengines running on the JUnit Platform via one of the following mechanisms.\n\n1. The `configurationParameter()` and `configurationParameters()` methods in\n `LauncherDiscoveryRequestBuilder` which\n is used to build a request supplied to the xref:advanced-topics/launcher-api.adoc[Launcher API].\n +\n When running tests via one of the tools provided by the JUnit Platform you can specify\n configuration parameters as follows:\n * xref:running-tests/console-launcher.adoc[Console Launcher]: use the `--config` command-line\n option.\n * xref:running-tests/build-support.adoc#gradle-config-params[Gradle]: use the `systemProperty` or\n `systemProperties` DSL.\n * xref:running-tests/build-support.adoc#maven-config-params[Maven Surefire provider]: use the\n `configurationParameters` property.\n2. The `configurationParametersResources()` method in `LauncherDiscoveryRequestBuilder`.\n +\n When running tests via the xref:running-tests/console-launcher.adoc[Console Launcher] you can\n specify custom configuration files using the `--config-resource` command-line option.\n3. JVM system properties.\n4. The JUnit Platform default configuration file: a file named `junit-platform.properties`\n in the root of the class path that follows the syntax rules for Java `Properties`\n files.\n\nNOTE: Configuration parameters are looked up in the exact order defined above.\nConsequently, configuration parameters supplied directly to the `Launcher` take\nprecedence over those supplied via custom configuration files, system properties, and the\ndefault configuration file. Similarly, configuration parameters supplied via system\nproperties take precedence over those supplied via the default configuration file.\n\n[[pattern]]\n== Pattern Matching Syntax\n\nThis section describes the pattern matching syntax that is applied to the _configuration\nparameters_ used for the following features.\n\n- xref:extensions/conditional-test-execution.adoc#deactivation[Deactivating Conditions]\n- xref:advanced-topics/launcher-api.adoc#listeners-custom-deactivation[Deactivating a TestExecutionListener]\n- xref:running-tests/stack-trace-pruning.adoc[]\n- xref:extensions/registering-extensions.adoc#registration-automatic-filtering[Filtering Auto-detected Extensions]\n\nIf the value for the given _configuration parameter_ consists solely of an asterisk\n(`+++*+++`), the pattern will match against all candidate classes. Otherwise, the value\nwill be treated as a comma-separated list of patterns where each pattern will be matched\nagainst the fully qualified class name (_FQCN_) of each candidate class. Any dot (`.`) in\na pattern will match against a dot (`.`) or a dollar sign (`$`) in a FQCN. Any asterisk\n(`+++*+++`) will match against one or more characters in a FQCN. All other characters in a\npattern will be matched one-to-one against a FQCN.\n\nExamples:\n\n- `+++*+++`: matches all candidate classes.\n- `+++org.junit.*+++`: matches all candidate classes under the `org.junit` base package and\n any of its subpackages.\n- `+++*.MyCustomImpl+++`: matches every candidate class whose simple class name is exactly\n `MyCustomImpl`.\n- `+++*System*+++`: matches every candidate class whose FQCN contains `System`.\n- `+++*System*+++, +++*Unit*+++`: matches every candidate class whose FQCN contains\n `System` or `Unit`.\n- `org.example.MyCustomImpl`: matches the candidate class whose FQCN is exactly\n `org.example.MyCustomImpl`.\n- `org.example.MyCustomImpl, org.example.TheirCustomImpl`: matches candidate classes whose\n FQCN is exactly `org.example.MyCustomImpl` or `org.example.TheirCustomImpl`.\n"
},
{
"path": "documentation/modules/ROOT/pages/running-tests/console-launcher.adoc",
"content": "= Console Launcher\n\nThe `{ConsoleLauncher}` is a command-line Java application that lets you launch the JUnit\nPlatform from the console. For example, it can be used to run JUnit Vintage and JUnit\nJupiter tests and print test execution results to the console.\n\nAn executable _Fat JAR_ (`junit-platform-console-standalone-{version}.jar`) that\ncontains the contents of all of its dependencies is published in the {Maven_Central}\nrepository under the\nhttps://repo1.maven.org/maven2/org/junit/platform/junit-platform-console-standalone[junit-platform-console-standalone]\ndirectory. It contains the contents of the following artifacts:\n\ninclude::partial$console-launcher-standalone-shadowed-artifacts.adoc[]\n\n[NOTE]\n====\nSince the `junit-platform-console-standalone` JAR contains the contents of all of its\ndependencies, its Maven POM does not declare any dependencies.\n\nFurthermore, it is not very likely that you would need to include a dependency on the\n`junit-platform-console-standalone` artifact in your project's Maven POM or Gradle build\nscript. On the contrary, the executable `junit-platform-console-standalone` JAR is\ntypically invoked directly from the command line or a shell script without a build script.\n\nIf you need to declare dependencies in your build script on some of the artifacts\ncontained in the `junit-platform-console-standalone` artifact, you should declare\ndependencies only on the JUnit artifacts that are used in your project. To simplify\ndependency management of JUnit artifacts in your build, you may wish to use the\n`junit-jupiter` aggregator artifact or `junit-bom`. See xref:appendix.adoc#dependency-metadata[Dependency Metadata] for\ndetails.\n====\n\nYou can https://docs.oracle.com/javase/tutorial/deployment/jar/run.html[run] the\nstandalone `ConsoleLauncher` as shown below.\n\n[source,console,subs=attributes+]\n----\n$ java -jar junit-platform-console-standalone-{version}.jar execute \n\n├─ JUnit Vintage\n│ └─ example.JUnit4Tests\n│ └─ standardJUnit4Test ✔\n└─ JUnit Jupiter\n ├─ StandardTests\n │ ├─ succeedingTest() ✔\n │ └─ skippedTest() ↷ for demonstration purposes\n └─ A special test case\n ├─ Custom test name containing spaces ✔\n ├─ ╯°□°)╯ ✔\n └─ 😱 ✔\n\nTest run finished after 64 ms\n[ 5 containers found ]\n[ 0 containers skipped ]\n[ 5 containers started ]\n[ 0 containers aborted ]\n[ 5 containers successful ]\n[ 0 containers failed ]\n[ 6 tests found ]\n[ 1 tests skipped ]\n[ 5 tests started ]\n[ 0 tests aborted ]\n[ 5 tests successful ]\n[ 0 tests failed ]\n----\n\nYou can also run the standalone `ConsoleLauncher` as shown below (for example, to include\nall jars in a directory):\n\n[source,console,subs=attributes+]\n----\n$ java -cp classes:testlib/* org.junit.platform.console.ConsoleLauncher \n----\n\n[[options]]\n== Subcommands and Options\n\nThe `{ConsoleLauncher}` provides the following subcommands:\n\n----\ninclude::partial$console-launcher-options.txt[]\n----\n\n[[options-discovering-tests]]\n=== Discovering tests\n\n----\ninclude::partial$console-launcher-discover-options.txt[]\n----\n\n[[options-executing-tests]]\n=== Executing tests\n\n.Exit Code\nNOTE: On successful runs, the `{ConsoleLauncher}` exits with a status code of `0`.\nAll non-zero codes indicate an error of some sort. For example, status code `1`\nis returned if any containers or tests failed. If no tests are discovered and the\n`--fail-if-no-tests` command-line option is supplied, the `ConsoleLauncher` exits\nwith a status code of `2`. Unexpected or invalid user input yields a status code\nof `3`. An exit code of `-1` indicates an unspecified error condition.\n\n----\ninclude::partial$console-launcher-execute-options.txt[]\n----\n\n[[options-listing-test-engines]]\n=== Listing test engines\n\n----\ninclude::partial$console-launcher-engines-options.txt[]\n----\n\n[[argument-files]]\n== Argument Files (@-files)\n\nOn some platforms you may run into system limitations on the length of a command line when\ncreating a command line with lots of options or with long arguments.\n\nThe `ConsoleLauncher` supports _argument files_, also known as _@-files_. Argument files\nare files that themselves contain arguments to be passed to the command. When the\nunderlying https://github.com/remkop/picocli[picocli] command line parser encounters an\nargument beginning with the character `@`, it expands the contents of that file into the\nargument list.\n\nThe arguments within a file can be separated by spaces or newlines. If an argument\ncontains embedded whitespace, the whole argument should be wrapped in double or single\nquotes -- for example, `\"-f=My Files/Stuff.java\"`.\n\nIf the argument file does not exist or cannot be read, the argument will be treated\nliterally and will not be removed. This will likely result in an \"unmatched argument\"\nerror message. You can troubleshoot such errors by executing the command with the\n`picocli.trace` system property set to `DEBUG`.\n\nMultiple _@-files_ may be specified on the command line. The specified path may be\nrelative to the current directory or absolute.\n\nYou can pass a real parameter with an initial `@` character by escaping it with an\nadditional `@` symbol. For example, `@@somearg` will become `@somearg` and will not be\nsubject to expansion.\n\n[[redirecting-stdout-and-stderr]]\n== Redirecting Standard Output/Error to Files\n\nYou can redirect the `System.out` (stdout) and `System.err` (stderr) output streams to\nfiles using the `--redirect-stdout` and `--redirect-stderr` options:\n\n[source,console,subs=attributes+]\n----\n$ java -jar junit-platform-console-standalone-{version}.jar \\\n --redirect-stdout=stdout.txt \\\n --redirect-stderr=stderr.txt\n----\n\n[NOTE]\n====\nIf the `--redirect-stdout` and `--redirect-stderr` arguments point to the same file, both\noutput streams will be redirected to that file.\n\nThe default charset is used for writing to the files.\n====\n\n[[color-customization]]\n== Color Customization\n\nThe colors used in the output of the `{ConsoleLauncher}` can be customized.\nThe option `--single-color` will apply a built-in monochrome style, while\n`--color-palette` will accept a properties file to override the\nhttps://en.wikipedia.org/wiki/ANSI_escape_code#Colors[ANSI SGR] color styling.\nThe properties file below demonstrates the default style:\n\n[source,properties,indent=0]\n----\nSUCCESSFUL = 32\nABORTED = 33\nFAILED = 31\nSKIPPED = 35\nCONTAINER = 35\nTEST = 34\nDYNAMIC = 35\nREPORTED = 37\n----\n"
},
{
"path": "documentation/modules/ROOT/pages/running-tests/discovery-issues.adoc",
"content": "= Discovery Issues\n\nTest engines may encounter issues during test discovery. For example, the declaration of a\ntest class or method may be invalid. To avoid such issues from going unnoticed, the JUnit\nPlatform provides a xref:advanced-topics/engines.adoc#discovery-issues[mechanism for test engines] to\nreport them with different severity levels:\n\nINFO::\nIndicates that the engine encountered something that could be potentially problematic, but\ncould also happen due to a valid setup or configuration.\n\nWARNING::\nIndicates that the engine encountered something that is problematic and might lead to\nunexpected behavior or will be removed or changed in a future release.\n\nERROR::\nIndicates that the engine encountered something that is definitely problematic and will\nlead to unexpected behavior.\n\nIf an engine reports an issue with a severity equal to or higher than a configurable\n_critical_ severity, its tests will not be executed. Instead, the engine will be reported\nas failed during execution with a `{DiscoveryIssueException}` listing all critical issues.\nNon-critical issues will be logged but will not prevent the engine from executing its\ntests. The `junit.platform.discovery.issue.severity.critical`\nxref:running-tests/configuration-parameters.adoc[configuration parameter] can be used to set the critical\nseverity level. Currently, the default value is `ERROR` but it may be changed in a future\nrelease.\n\nTIP: To surface all discovery issues in your project, it is recommended to set the\n`junit.platform.discovery.issue.severity.critical` configuration parameter to `INFO`.\n\nIn addition, registered `{LauncherDiscoveryListener}` implementations can receive\ndiscovery issues via the `issueEncountered()` method. This allows IDEs and build tools to\nreport issues to the user in a more user-friendly way. For example, IDEs may choose to\ndisplay all issues in a list or table.\n"
},
{
"path": "documentation/modules/ROOT/pages/running-tests/discovery-selectors.adoc",
"content": "= Discovery Selectors\n\nThe JUnit Platform provides a rich set of discovery selectors that can be used to specify\nwhich tests should be discovered or executed.\n\nDiscovery selectors can be created programmatically using the factory methods in the\n`{DiscoverySelectors}` class, specified declaratively via annotations when using the\nxref:advanced-topics/junit-platform-suite-engine.adoc[], via options of the xref:running-tests/console-launcher.adoc[], or\ngenerically as strings via their identifiers.\n\nThe following discovery selectors are provided out of the box:\n\n|===\n| Java Type | API | Annotation | Console Launcher | Identifier\n\n| `{ClasspathResourceSelector}` | `{DiscoverySelectors_selectClasspathResource}` | `{SelectClasspathResource}` | `--select-resource /foo.csv` | `resource:/foo.csv`\n| `{ClasspathRootSelector}` | `{DiscoverySelectors_selectClasspathRoots}` | -- | `--scan-classpath bin` | `classpath-root:bin`\n| `{ClassSelector}` | `{DiscoverySelectors_selectClass}` | `{SelectClasses}` | `--select-class com.acme.Foo` | `class:com.acme.Foo`\n| `{DirectorySelector}` | `{DiscoverySelectors_selectDirectory}` | `{SelectDirectories}` | `--select-directory foo/bar` | `directory:foo/bar`\n| `{FileSelector}` | `{DiscoverySelectors_selectFile}` | `{SelectFile}` | `--select-file dir/foo.txt` | `file:dir/foo.txt`\n| `{IterationSelector}` | `{DiscoverySelectors_selectIteration}` | `{Select}(\"\")` | `--select-iteration method=com.acme.Foo#m[1..2]` | `iteration:method:com.acme.Foo#m[1..2]`\n| `{MethodSelector}` | `{DiscoverySelectors_selectMethod}` | `{SelectMethod}` | `--select-method com.acme.Foo#m` | `method:com.acme.Foo#m`\n| `{ModuleSelector}` | `{DiscoverySelectors_selectModule}` | `{SelectModules}` | `--select-module com.acme` | `module:com.acme`\n| `{NestedClassSelector}` | `{DiscoverySelectors_selectNestedClass}` | `{Select}(\"\")` | `--select ` | `nested-class:com.acme.Foo/Bar`\n| `{NestedMethodSelector}` | `{DiscoverySelectors_selectNestedMethod}` | `{Select}(\"\")` | `--select ` | `nested-method:com.acme.Foo/Bar#m`\n| `{PackageSelector}` | `{DiscoverySelectors_selectPackage}` | `{SelectPackages}` | `--select-package com.acme.foo` | `package:com.acme.foo`\n| `{UniqueIdSelector}` | `{DiscoverySelectors_selectUniqueId}` | `{Select}(\"\")` | `--select-unique-id ` | `uid:[engine:Foo]/[segment:Bar]`\n| `{UriSelector}` | `{DiscoverySelectors_selectUri}` | `{SelectUris}` | `--select-uri \\file:///foo.txt` | `uri:file:///foo.txt`\n|===\n"
},
{
"path": "documentation/modules/ROOT/pages/running-tests/ide-support.adoc",
"content": "= IDE Support\n\n[[intellij-idea]]\n== IntelliJ IDEA\n\nIntelliJ IDEA supports running tests on the JUnit Platform since version 2016.2. For more\ninformation, please consult this https://jb.gg/junit-idea/[IntelliJ IDEA resource]. Note,\nhowever, that it is recommended to use IDEA 2017.3 or newer since more recent versions of\nIDEA download the following JARs automatically based on the API version used in the\nproject: `junit-platform-launcher`, `junit-jupiter-engine`, and `junit-vintage-engine`.\n\nIn order to use a different JUnit version (e.g., {version}), you may need to\ninclude the corresponding versions of the `junit-platform-launcher`,\n`junit-jupiter-engine`, and `junit-vintage-engine` JARs in the classpath.\n\n.Additional Gradle Dependencies\n[source,groovy]\n[subs=attributes+]\n----\ntestImplementation(platform(\"org.junit:junit-bom:{version}\"))\ntestRuntimeOnly(\"org.junit.platform:junit-platform-launcher\")\ntestRuntimeOnly(\"org.junit.jupiter:junit-jupiter-engine\")\ntestRuntimeOnly(\"org.junit.vintage:junit-vintage-engine\")\n----\n\n.Additional Maven Dependencies\n[source,xml]\n[subs=attributes+]\n----\n\n\n\t\n\t\torg.junit.platform \n\t\tjunit-platform-launcher \n\t\ttest \n\t \n\t\n\t\torg.junit.jupiter \n\t\tjunit-jupiter-engine \n\t\ttest \n\t \n\t\n\t\torg.junit.vintage \n\t\tjunit-vintage-engine \n\t\ttest \n\t \n \n\n\t\n\t\t\n\t\t\torg.junit \n\t\t\tjunit-bom \n\t\t\t{version} \n\t\t\tpom \n\t\t\timport \n\t\t \n\t \n \n----\n\n[[eclipse]]\n== Eclipse\n\nEclipse IDE offers support for the JUnit Platform since the Eclipse Oxygen.1a (4.7.1a)\nrelease.\n\nFor more information on using JUnit Platform in Eclipse consult the official _Eclipse\nsupport for JUnit 5_ section of the\nhttps://www.eclipse.org/eclipse/news/4.7.1a/#junit-5-support[Eclipse Project Oxygen.1a\n(4.7.1a) - New and Noteworthy] documentation.\n\n[[netbeans]]\n== NetBeans\n\nNetBeans offers support for JUnit Jupiter and the JUnit Platform since the\nhttps://netbeans.apache.org/download/nb100/nb100.html[Apache NetBeans 10.0 release].\n\nFor more information consult the JUnit 5 section of the\nhttps://netbeans.apache.org/download/nb100/index.html#_junit_5[Apache NetBeans 10.0\nrelease notes].\n\n[[vscode]]\n== Visual Studio Code\n\nhttps://code.visualstudio.com/[Visual Studio Code] supports JUnit Jupiter and the JUnit\nPlatform via the\nhttps://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-test[Java Test\nRunner] extension which is installed by default as part of the\nhttps://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-pack[Java\nExtension Pack].\n\nFor more information consult the _Testing_ section of the\nhttps://code.visualstudio.com/docs/languages/java#_testing[Java in Visual Studio Code]\ndocumentation.\n\n[[other]]\n== Other IDEs\n\nIf you are using an editor or IDE other than one of those listed in the previous sections,\nand it doesn't support running tests on the JUnit Platform, you can use the\nxref:running-tests/console-launcher.adoc[] to run them from the command line.\n"
},
{
"path": "documentation/modules/ROOT/pages/running-tests/intro.adoc",
"content": "= Running Tests\n\nThis section explains how to run tests from IDEs and build tools.\n"
},
{
"path": "documentation/modules/ROOT/pages/running-tests/source-launcher.adoc",
"content": "= Source Launcher\n\nStarting with Java 25 it is possible to write minimal source code test programs\nusing the `org.junit.start` module.\n\nFor example, create a `HelloTests.java` file with the following content:\n\n[source,java]\n----\nimport module org.junit.start;\n\nvoid main() {\n JUnit.run();\n}\n\n@Test\nvoid stringLength() {\n Assertions.assertEquals(11, \"Hello JUnit\".length());\n}\n----\n\nWith all required modular JAR files available in a local `lib/` directory, the\nfollowing Java 25+ command will discover and execute tests using the JUnit Platform.\nIt will also print the result tree to the console.\n\n[source,shell]\n----\njava --module-path lib --add-modules org.junit.start HelloTests.java\n╷\n└─ JUnit Jupiter ✔\n └─ HelloTests ✔\n └─ stringLength() ✔\n----\n\nFor details, please refer to the Javadoc of the `{JUnit}` class.\n"
},
{
"path": "documentation/modules/ROOT/pages/running-tests/stack-trace-pruning.adoc",
"content": "= Stack Trace Pruning\n\nThe JUnit Platform provides built-in support for pruning stack traces produced by failing\ntests. This feature is enabled by default but can be disabled by setting the\n`junit.platform.stacktrace.pruning.enabled` _configuration parameter_ to `false`.\n\nWhen enabled, all calls from the `org.junit`, `jdk.internal.reflect`, and `sun.reflect`\npackages are removed from the stack trace, unless the calls occur after the test itself\nor any of its ancestors. For that reason, calls to `{Assertions}` or `{Assumptions}` will\nnever be excluded.\n\nIn addition, all elements prior to and including the first call from the JUnit Platform\n`Launcher` will be removed.\n"
},
{
"path": "documentation/modules/ROOT/pages/running-tests/tags.adoc",
"content": "= Tags\n\nTags are a JUnit Platform concept for marking and filtering tests. The programming model\nfor adding tags to containers and tests is defined by the testing framework. For example,\nin JUnit Jupiter based tests, the `@Tag` annotation (see\nxref:writing-tests/tagging-and-filtering.adoc[]) should be used. For JUnit 4 based tests, the\nVintage engine maps `@Category` annotations to tags (see\nxref:migrating-from-junit4.adoc#categories-support[Categories Support]). Other testing frameworks may define their\nown annotation or other means for users to specify tags.\n\n[[syntax-rules]]\n== Syntax Rules for Tags\n\nRegardless how a tag is specified, the JUnit Platform enforces the following rules:\n\n* A tag must not be `null` or _blank_.\n* A _stripped_ tag must not contain whitespace.\n* A _stripped_ tag must not contain ISO control characters.\n* A _stripped_ tag must not contain any of the following _reserved characters_.\n- `,`: _comma_\n- `(`: _left parenthesis_\n- `)`: _right parenthesis_\n- `&`: _ampersand_\n- `|`: _vertical bar_\n- `!`: _exclamation point_\n\nNOTE: In the above context, \"stripped\" means that leading and trailing whitespace\ncharacters have been removed using `java.lang.String.strip()`.\n\n[[expressions]]\n== Tag Expressions\n\nTag expressions are boolean expressions with the operators `!`, `&` and `|`. In addition,\n`(` and `)` can be used to adjust for operator precedence.\n\nTwo special expressions are supported, `any()` and `none()`, which select all tests _with_\nany tags at all, and all tests _without_ any tags, respectively.\nThese special expressions may be combined with other expressions just like normal tags.\n\n.Operators (in descending order of precedence)\n|===\n| Operator | Meaning | Associativity\n\n| `!` | not | right\n| `&` | and | left\n| `\\|` | or | left\n|===\n\nIf you are tagging your tests across multiple dimensions, tag expressions help you to\nselect which tests to execute. When tagging by test type (e.g., _micro_, _integration_,\n_end-to-end_) and feature (e.g., *product*, *catalog*, *shipping*), the following tag\nexpressions can be useful.\n\n[%header,cols=\"40,60\"]\n|===\n| Tag Expression\n| Selection\n\n| `+++product+++`\n| all tests for *product*\n\n| `+++catalog \\| shipping+++`\n| all tests for *catalog* plus all tests for *shipping*\n\n| `+++catalog & shipping+++`\n| all tests for the intersection between *catalog* and *shipping*\n\n| `+++product & !end-to-end+++`\n| all tests for *product*, but not the _end-to-end_ tests\n\n| `+++(micro \\| integration) & (product \\| shipping)+++`\n| all _micro_ or _integration_ tests for *product* or *shipping*\n|===\n"
},
{
"path": "documentation/modules/ROOT/pages/running-tests/using-listeners-and-interceptors.adoc",
"content": "= Using Listeners and Interceptors\n\nThe JUnit Platform provides the following listener APIs that allow JUnit, third parties,\nand custom user code to react to events fired at various points during the discovery and\nexecution of a `TestPlan`.\n\n* `{LauncherSessionListener}`: receives events when a `{LauncherSession}` is opened and\n closed.\n* `{LauncherInterceptor}`: intercepts test discovery and execution in the context of a\n `LauncherSession`.\n* `{LauncherDiscoveryListener}`: receives events that occur during test discovery.\n* `{TestExecutionListener}`: receives events that occur during test execution.\n\nThe `LauncherSessionListener` API is typically implemented by build tools or IDEs and\nregistered automatically for you in order to support some feature of the build tool or IDE.\n\nThe `LauncherDiscoveryListener` and `TestExecutionListener` APIs are often implemented in\norder to produce some form of report or to display a graphical representation of the test\nplan in an IDE. Such listeners may be implemented and automatically registered by a build\ntool or IDE, or they may be included in a third-party library – potentially registered\nfor you automatically. You can also implement and register your own listeners.\n\nFor details on registering and configuring listeners, see the following sections of this\nguide.\n\n* xref:advanced-topics/launcher-api.adoc#launcher-session-listeners-custom[Registering a LauncherSessionListener]\n* xref:advanced-topics/launcher-api.adoc#launcher-interceptors-custom[Registering a LauncherInterceptor]\n* xref:advanced-topics/launcher-api.adoc#launcher-discovery-listeners-custom[Registering a LauncherDiscoveryListener]\n* xref:advanced-topics/launcher-api.adoc#listeners-custom[Registering a TestExecutionListener]\n* xref:advanced-topics/launcher-api.adoc#listeners-config[Configuring a TestExecutionListener]\n* xref:advanced-topics/launcher-api.adoc#listeners-custom-deactivation[Deactivating a TestExecutionListener]\n\nThe JUnit Platform provides the following listeners which you may wish to use with your\ntest suite.\n\nxref:advanced-topics/junit-platform-reporting.adoc[] ::\n `{LegacyXmlReportGeneratingListener}` can be used via the\n xref:running-tests/console-launcher.adoc[] or registered manually to generate XML reports\n compatible with the de facto standard for JUnit 4 based test reports.\n+\n`{OpenTestReportGeneratingListener}` generates an XML report in the event-based format\nspecified by {OpenTestReporting}. It is auto-registered and can be enabled and\nconfigured via xref:running-tests/configuration-parameters.adoc[].\n+\nSee xref:advanced-topics/junit-platform-reporting.adoc[] for details.\n\n<> ::\n `FlightRecordingExecutionListener` and `FlightRecordingDiscoveryListener` that generate\n Java Flight Recorder events during test discovery and execution.\n\n`{LoggingListener}` ::\n `TestExecutionListener` for logging informational messages for all events via a\n `BiConsumer` that consumes `Throwable` and `Supplier`.\n\n`{SummaryGeneratingListener}` ::\n `TestExecutionListener` that generates a summary of the test execution which can be\n printed via a `PrintWriter`.\n\n`{UniqueIdTrackingListener}` ::\n `TestExecutionListener` that that tracks the unique IDs of all tests that were skipped\n or executed during the execution of the `TestPlan` and generates a file containing the\n unique IDs once execution of the `TestPlan` has finished.\n\n[[recorder]]\n== Flight Recorder Support\n\nThe JUnit Platform provides opt-in support for generating Flight Recorder events.\nhttps://openjdk.java.net/jeps/328[JEP 328] describes the Java Flight Recorder (JFR) as\nfollows.\n\n> Flight Recorder records events originating from applications, the JVM, and the OS.\nEvents are stored in a single file that can be attached to bug reports and examined by\nsupport engineers, allowing after-the-fact analysis of issues in the period leading up\nto a problem.\n\nIn order to record Flight Recorder events generated while running tests, you need to\nstart flight recording when launching a test suite via the following java command line\noption.\n\n -XX:StartFlightRecording:filename=...\n\nPlease consult the manual of your build tool for the appropriate commands.\n\nTo analyze the recorded events, use the\nhttps://docs.oracle.com/en/java/javase/17/docs/specs/man/jfr.html[jfr]\ncommand line tool shipped with recent JDKs or open the recording file with\nhttps://jdk.java.net/jmc/[JDK Mission Control].\n"
},
{
"path": "documentation/modules/ROOT/pages/writing-tests/annotations.adoc",
"content": "= Annotations\n\nJUnit Jupiter supports the following annotations for configuring tests and extending the\nframework.\n\nUnless otherwise stated, all core annotations are located in the `{api-package}` package\nin the `junit-jupiter-api` module.\n\n`*@Test*`:: Denotes that a method is a test method. Unlike JUnit 4's `@Test` annotation,\nthis annotation does not declare any attributes, since test extensions in JUnit Jupiter\noperate based on their own dedicated annotations. Such methods are inherited unless they\nare overridden.\n\n`*@ParameterizedTest*`:: Denotes that a method is a\nxref:writing-tests/parameterized-classes-and-tests.adoc[parameterized test]. Such methods are inherited\nunless they are overridden.\n\n`*@RepeatedTest*`:: Denotes that a method is a test template for a\nxref:writing-tests/repeated-tests.adoc[repeated test]. Such methods are inherited unless they\nare overridden.\n\n`*@TestFactory*`:: Denotes that a method is a test factory for\nxref:writing-tests/dynamic-tests.adoc[dynamic tests]. Such methods are inherited unless they are\noverridden.\n\n`*@TestTemplate*`:: Denotes that a method is a\nxref:writing-tests/test-templates.adoc[template for a test case] designed to be invoked multiple\ntimes depending on the number of invocation contexts returned by the registered\nxref:extensions/providing-invocation-contexts-for-test-templates.adoc[providers]. Such methods are inherited unless they are\noverridden.\n\n`*@TestClassOrder*`:: Used to configure the\nxref:writing-tests/test-execution-order.adoc#classes[test class execution order] for `@Nested`\ntest classes in the annotated test class. Such annotations are inherited.\n\n`*@TestMethodOrder*`:: Used to configure the\nxref:writing-tests/test-execution-order.adoc#methods[test method execution order] for the\nannotated test class; similar to JUnit 4's `@FixMethodOrder`. Such annotations are\ninherited.\n\n`*@TestInstance*`:: Used to configure the\nxref:writing-tests/test-instance-lifecycle.adoc[test instance lifecycle] for the annotated test\nclass. Such annotations are inherited.\n\n`*@DisplayName*`:: Declares a custom xref:writing-tests/display-names.adoc[display name] for the\ntest class or test method. Such annotations are not inherited.\n\n`*@DisplayNameGeneration*`:: Declares a custom\nxref:writing-tests/display-names.adoc#generator[display name generator] for the test class. Such\nannotations are inherited.\n\n`*@BeforeEach*`:: Denotes that the annotated method should be executed _before_ *each*\n`@Test`, `@RepeatedTest`, `@ParameterizedTest`, or `@TestFactory` method in the current\nclass; analogous to JUnit 4's `@Before`. Such methods are inherited unless they are\noverridden.\n\n`*@AfterEach*`:: Denotes that the annotated method should be executed _after_ *each*\n`@Test`, `@RepeatedTest`, `@ParameterizedTest`, or `@TestFactory` method in the current\nclass; analogous to JUnit 4's `@After`. Such methods are inherited unless they are\noverridden.\n\n`*@BeforeAll*`:: Denotes that the annotated method should be executed _before_ *all*\n`@Test`, `@RepeatedTest`, `@ParameterizedTest`, and `@TestFactory` methods in the current\ntop-level or `@Nested` test class; analogous to JUnit 4's `@BeforeClass`. Such methods are\ninherited unless they are overridden and must be `static` unless the \"per-class\"\nxref:writing-tests/test-instance-lifecycle.adoc[test instance lifecycle] is used.\n\n`*@AfterAll*`:: Denotes that the annotated method should be executed _after_ *all*\n`@Test`, `@RepeatedTest`, `@ParameterizedTest`, and `@TestFactory` methods in the current\ntop-level or `@Nested` test class; analogous to JUnit 4's `@AfterClass`. Such methods are\ninherited unless they are overridden and must be `static` unless the \"per-class\"\nxref:writing-tests/test-instance-lifecycle.adoc[test instance lifecycle] is used.\n\n`*@ParameterizedClass*`:: Denotes that the annotated class is a\nxref:writing-tests/parameterized-classes-and-tests.adoc[parameterized class]. Such annotations are\ninherited.\n\n`*@BeforeParameterizedClassInvocation*`:: Denotes that the annotated method should be\nexecuted once _before_ each invocation of a\nxref:writing-tests/parameterized-classes-and-tests.adoc[parameterized class]. Such methods are inherited\nunless they are overridden.\n\n`*@AfterParameterizedClassInvocation*`:: Denotes that the annotated method should be\nexecuted once _after_ each invocation of a\nxref:writing-tests/parameterized-classes-and-tests.adoc[parameterized class]. Such methods are inherited\nunless they are overridden.\n\n`*@ClassTemplate*`:: Denotes that the annotated class is a\nxref:writing-tests/class-templates.adoc[template for a test class] designed to be executed\nmultiple times depending on the number of invocation contexts returned by the registered\nxref:extensions/providing-invocation-contexts-for-class-templates.adoc[providers]. Such annotations are inherited.\n\n`*@Nested*`:: Denotes that the annotated class is a non-static\nxref:writing-tests/nested-tests.adoc[nested test class]. Such annotations are not inherited.\n\n`*@Tag*`:: Used to declare\nxref:writing-tests/tagging-and-filtering.adoc[tags for filtering tests], either at the class or\nmethod level; analogous to test groups in TestNG or Categories in JUnit 4. Such\nannotations are inherited at the class level but not at the method level.\n\n`*@Disabled*`:: Used to xref:writing-tests/disabling-tests.adoc[disable] a test class or test method;\nanalogous to JUnit 4's `@Ignore`. Such annotations are not inherited.\n\n`*@AutoClose*`:: Denotes that the annotated field represents a resource that will be\nxref:writing-tests/built-in-extensions.adoc#AutoClose[automatically closed] after test\nexecution. Such fields are inherited.\n\n`*@Timeout*`:: Used to fail a test, test factory, test template, or lifecycle method if\nits execution exceeds a given duration. Such annotations are inherited.\n\n`*@TempDir*`:: Used to supply a\nxref:writing-tests/built-in-extensions.adoc#TempDirectory[temporary directory] via field\ninjection or parameter injection in a test class constructor, lifecycle method, or test\nmethod; located in the `org.junit.jupiter.api.io` package. Such fields are inherited.\n\n`*@ExtendWith*`:: Used to\nxref:extensions/registering-extensions.adoc#registration-declarative[register extensions declaratively]. Such\nannotations are inherited.\n\n`*@RegisterExtension*`:: Used to\nxref:extensions/registering-extensions.adoc#registration-programmatic[register extensions programmatically] via fields.\nSuch fields are inherited.\n\nWARNING: Some annotations may currently be _experimental_. Consult the table in\nxref:api-evolution.adoc#experimental-apis[Experimental APIs] for details.\n\n[[annotations]]\n== Meta-Annotations and Composed Annotations\n\nJUnit Jupiter annotations can be used as _meta-annotations_. That means that you can\ndefine your own _composed annotation_ that will automatically _inherit_ the semantics of\nits meta-annotations.\n\nFor example, instead of copying and pasting `@Tag(\"fast\")` throughout your code base (see\nxref:writing-tests/tagging-and-filtering.adoc[]), you can create a custom _composed annotation_\nnamed `@Fast` as follows. `@Fast` can then be used as a drop-in replacement for\n`@Tag(\"fast\")`.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/Fast.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/Fast.kt[tags=user_guide]\n----\n--\n====\n\nThe following `@Test` method demonstrates usage of the `@Fast` annotation.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\n@Fast\n@Test\nvoid myFastTest() {\n // ...\n}\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\n@Fast\n@Test\nfun myFastTest() {\n // ...\n}\n----\n--\n====\n\nYou can even take that one step further by introducing a custom `@FastTest` annotation\nthat can be used as a drop-in replacement for `@Tag(\"fast\")` _and_ `@Test`.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/FastTest.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/FastTest.kt[tags=user_guide]\n----\n--\n====\n\nJUnit automatically recognizes the following as a `@Test` method that is tagged with\n\"fast\".\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\n@FastTest\nvoid myFastTest() {\n // ...\n}\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\n@FastTest\nfun myFastTest() {\n // ...\n}\n----\n--\n====\n"
},
{
"path": "documentation/modules/ROOT/pages/writing-tests/assertions.adoc",
"content": "= Assertions\n\nJUnit Jupiter comes with many of the assertion methods that JUnit 4 has and adds a few\nthat lend themselves well to being used with Java lambdas. All JUnit Jupiter assertions\nare `static` methods in the `{Assertions}` class.\n\nAssertion methods optionally accept the assertion message as their third parameter, which\ncan be either a `String` or a `Supplier`.\n\nWhen using a `Supplier` (e.g., a lambda expression), the message is evaluated\nlazily. This can provide a performance benefit, especially if message construction is\ncomplex or time-consuming, as it is only evaluated when the assertion fails.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/AssertionsDemo.java[tags=user_guide]\n----\n\n[[preemptive-timeouts]]\n[WARNING]\n.Preemptive Timeouts with `assertTimeoutPreemptively()`\n====\nThe various `assertTimeoutPreemptively()` methods in the `Assertions` class execute\nthe provided `executable` or `supplier` in a different thread than that of the calling\ncode. This behavior can lead to undesirable side effects if the code that is executed\nwithin the `executable` or `supplier` relies on `java.lang.ThreadLocal` storage.\n\nOne common example of this is the transactional testing support in the Spring Framework.\nSpecifically, Spring's testing support binds transaction state to the current thread (via\na `ThreadLocal`) before a test method is invoked. Consequently, if an `executable` or\n`supplier` provided to `assertTimeoutPreemptively()` invokes Spring-managed components\nthat participate in transactions, any actions taken by those components will not be rolled\nback with the test-managed transaction. On the contrary, such actions will be committed to\nthe persistent store (e.g., relational database) even though the test-managed transaction\nis rolled back.\n\nSimilar side effects may be encountered with other frameworks that rely on\n`ThreadLocal` storage.\n====\n\n[[kotlin]]\n== Kotlin Assertion Support\n\nJUnit Jupiter also comes with a few assertion methods that lend themselves well to being\nused in https://kotlinlang.org/[Kotlin]. All JUnit Jupiter Kotlin assertions are top-level\nfunctions in the `org.junit.jupiter.api` package.\n\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/KotlinAssertionsDemo.kt[tags=user_guide]\n----\n\n[[third-party]]\n== Third-party Assertion Libraries\n\nEven though the assertion facilities provided by JUnit Jupiter are sufficient for many\ntesting scenarios, there are times when more power and additional functionality are\ndesired or required. In such cases, the JUnit team recommends the use of third-party\nassertion libraries such as {AssertJ}, {Hamcrest}, {Truth}, etc. Developers are therefore\nfree to use the assertion library of their choice.\n\nFor example, the following demonstrates how to use the `assertThat()` support from AssertJ\nin a JUnit Jupiter test. As long as the AssertJ library has been added to the classpath,\nyou can statically import methods such as `assertThat()`, `assertThatException()`, etc.\nfrom `org.assertj.core.api.Assertions` and then use them in tests like in the\n`assertWithAssertJ()` method below.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/AssertJAssertionsDemo.java[tags=user_guide]\n----\n\n[TIP]\n.Excluding Jupiter’s Assertions From a Project’s Classpath\n====\nIf you would like to enforce that all your tests use a certain third-party assertion\nlibrary instead of Jupiter's, you can set up a rule using {Checkstyle} or another static\nanalysis tool that fails the build if Jupiter's `Assertions` class is used.\n\n[source,xml]\n----\n\n\n\n\t\n \n\t\t\t\n\t\t\t\n\t\t\t\n\t\t\t\n\t\t \n\t \n \n----\n====\n"
},
{
"path": "documentation/modules/ROOT/pages/writing-tests/assumptions.adoc",
"content": "= Assumptions\n\nAssumptions are typically used whenever it does not make sense to continue execution of a\ngiven test — for example, if the test depends on something that does not exist in the\ncurrent runtime environment.\n\n* When an assumption is valid, the assumption method does not throw an exception, and\n execution of the test continues as usual.\n* When an assumption is invalid, the assumption method throws an exception of type\n `org.opentest4j.TestAbortedException` to signal that the test should be aborted instead\n of marked as a failure.\n\nJUnit Jupiter comes with a subset of the _assumption_ methods that JUnit 4 provides and\nadds a few that lend themselves well to being used with Java lambda expressions and method\nreferences.\n\nAll JUnit Jupiter assumptions are static methods in the `{Assumptions}` class.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/AssumptionsDemo.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/AssumptionsDemo.kt[tags=user_guide]\n----\n--\n====\n\nNOTE: It is also possible to use methods from JUnit 4's `org.junit.Assume` class for\nassumptions. Specifically, JUnit Jupiter supports JUnit 4's `AssumptionViolatedException`\nto signal that a test should be aborted instead of marked as a failure.\n\nTIP: If you use AssertJ for assertions, you may also wish to use AssertJ for assumptions.\nTo do so, you can statically import the `assumeThat()` method from\n`org.assertj.core.api.Assumptions` and then use AssertJ's fluent API to specify your\nassumptions.\n"
},
{
"path": "documentation/modules/ROOT/pages/writing-tests/built-in-extensions.adoc",
"content": "= Built-in Extensions\n\nWhile the JUnit team encourages reusable extensions to be packaged and maintained in\nseparate libraries, JUnit Jupiter includes a few user-facing extension implementations\nthat are considered so generally useful that users shouldn't have to add another\ndependency.\n\n[[TempDirectory]]\n== The @TempDir Extension\n\nThe `{TempDirectory}` extension is used to create and clean up a temporary\ndirectory for an individual test or all tests in a test class. It is registered by\ndefault. To use it, annotate a non-final, unassigned field of type `java.nio.file.Path` or\n`java.io.File` with `{TempDir}` or add a parameter of type `java.nio.file.Path` or\n`java.io.File` annotated with `@TempDir` to a test class constructor, lifecycle method, or\ntest method.\n\nFor example, the following test declares a parameter annotated with `@TempDir` for a\nsingle test method, creates and writes to a file in the temporary directory, and checks\nits content.\n\n.A test method that requires a temporary directory\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/TempDirectoryDemo.java[tags=user_guide_parameter_injection]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/TempDirectoryDemo.kt[tags=user_guide_parameter_injection]\n----\n--\n====\n\nYou can inject multiple temporary directories by specifying multiple annotated parameters.\n\n.A test method that requires multiple temporary directories\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/TempDirectoryDemo.java[tags=user_guide_multiple_directories]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/TempDirectoryDemo.kt[tags=user_guide_multiple_directories]\n----\n--\n====\n\nThe following example stores a _shared_ temporary directory in a `static` field. This\nallows the same `sharedTempDir` to be used in all lifecycle methods and test methods of\nthe test class. For better isolation, you should use an instance field or constructor\ninjection so that each test method uses a separate directory.\n\n.A test class that shares a temporary directory across test methods\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/TempDirectoryDemo.java[tags=user_guide_field_injection]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/TempDirectoryDemo.kt[tags=user_guide_field_injection]\n----\n--\n====\n\nThe `@TempDir` annotation has an optional `cleanup` attribute that can be set to either\n`NEVER`, `ON_SUCCESS`, or `ALWAYS`. If the cleanup mode is set to `NEVER`, the temporary\ndirectory will not be deleted after the test completes. If it is set to `ON_SUCCESS`, the\ntemporary directory will only be deleted after the test if the test completed successfully.\n\nThe default cleanup mode is `ALWAYS`. You can use the\n`junit.jupiter.tempdir.cleanup.mode.default`\nxref:running-tests/configuration-parameters.adoc[configuration parameter] to override this default.\n\n.A test class with a temporary directory that doesn't get cleaned up\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/TempDirectoryDemo.java[tags=user_guide_cleanup_mode]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/TempDirectoryDemo.kt[tags=user_guide_cleanup_mode]\n----\n--\n====\n\n[[TempDirFactory]]\n=== Factories\n\n`@TempDir` supports the programmatic creation of temporary directories via the optional\n`factory` attribute. This is typically used to gain control over the temporary directory\ncreation, like defining the parent directory or the file system that should be used.\n\nFactories can be created by implementing `{TempDirFactory}`. Implementations must provide a\nno-args constructor and should not make any assumptions regarding when and how many times\nthey are instantiated, but they can assume that their `createTempDirectory(...)` and\n`close()` methods will both be called once per instance, in this order, and from the same\nthread.\n\nThe default implementation available in Jupiter delegates directory creation to\n`java.nio.file.Files::createTempDirectory` which uses the default file system and the\nsystem's temporary directory as the parent directory. It passes `junit-` as the prefix\nstring of the generated directory name to help identify it as a created by JUnit.\n\nThe following example defines a factory that uses the test name as the directory name\nprefix instead of the `junit` constant value.\n\n.A test class with a temporary directory having the test name as the directory name prefix\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/TempDirectoryDemo.java[tags=user_guide_factory_name_prefix]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/TempDirectoryDemo.kt[tags=user_guide_factory_name_prefix]\n----\n--\n====\n\nIt is also possible to use an in-memory file system like `{Jimfs}` for the creation of the\ntemporary directory. The following example demonstrates how to achieve that.\n\n.A test class with a temporary directory created with the Jimfs in-memory file system\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/TempDirectoryDemo.java[tags=user_guide_factory_jimfs]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/TempDirectoryDemo.kt[tags=user_guide_factory_jimfs]\n----\n--\n====\n\n`@TempDir` can also be used as a xref:writing-tests/annotations.adoc#annotations[meta-annotation] to\nreduce repetition. The following code listing shows how to create a custom `@JimfsTempDir`\nannotation that can be used as a drop-in replacement for\n`@TempDir(factory = JimfsTempDirFactory.class)`.\n\n.A custom annotation meta-annotated with `@TempDir`\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/TempDirectoryDemo.java[tags=user_guide_composed_annotation]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/TempDirectoryDemo.kt[tags=user_guide_composed_annotation]\n----\n--\n====\n\nThe following example demonstrates how to use the custom `@JimfsTempDir` annotation.\n\n.A test class using the custom annotation\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/TempDirectoryDemo.java[tags=user_guide_composed_annotation_usage]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/TempDirectoryDemo.kt[tags=user_guide_composed_annotation_usage]\n----\n--\n====\n\nMeta-annotations or additional annotations on the field or parameter the `TempDir`\nannotation is declared on might expose additional attributes to configure the factory.\nSuch annotations and related attributes can be accessed via the `AnnotatedElementContext`\nparameter of the `createTempDirectory(...)` method.\n\nYou can use the `junit.jupiter.tempdir.factory.default`\nxref:running-tests/configuration-parameters.adoc[configuration parameter] to specify the\nfully qualified class name of the `{TempDirFactory}` you would like to use by default. Just\nlike for factories configured via the `factory` attribute of the `@TempDir` annotation,\nthe supplied class has to implement the `{TempDirFactory}` interface. The default factory\nwill be used for all `@TempDir` annotations unless the `factory` attribute of the\nannotation specifies a different factory.\n\nIn summary, the factory for a temporary directory is determined according to the following\nprecedence rules:\n\n1. The `factory` attribute of the `@TempDir` annotation, if present\n2. The default `{TempDirFactory}` configured via the configuration\nparameter, if present\n3. Otherwise, `org.junit.jupiter.api.io.TempDirFactory$Standard` will be used.\n\n[[TempDirDeletionStrategy]]\n=== Deletion\n\n`@TempDir` supports the programmatic deletion of temporary directories via the optional\n`deletionStrategy` attribute. This is typically used to gain control over what happens\nwhen deletion of a file or directory fails.\n\nDeletion strategies can be created by implementing `{TempDirDeletionStrategy}`.\nImplementations must provide a no-args constructor.\n\nJupiter ships with two built-in deletion strategies:\n\n* `{TempDirDeletionStrategyStandard}` (the default): attempts to delete all files and\n directories recursively, retrying with permission resets on failure. Paths that still\n cannot be deleted are scheduled for deletion on JVM exit, if possible. Additionally,\n the test is failed.\n* `{TempDirDeletionStrategyIgnoreFailures}`: delegates to `{TempDirDeletionStrategyStandard}`\n but suppresses deletion failures by logging a warning instead of failing the test.\n\nThe following example uses `{TempDirDeletionStrategyIgnoreFailures}` so that any deletion\nfailures are only logged.\n\n.A test class with a temporary directory that ignores deletion failures\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/TempDirectoryDemo.java[tags=user_guide_deletion_strategy]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/TempDirectoryDemo.kt[tags=user_guide_deletion_strategy]\n----\n--\n====\n\nYou can use the `junit.jupiter.tempdir.deletion.strategy.default`\nxref:running-tests/configuration-parameters.adoc[configuration parameter] to specify the\nfully qualified class name of the `{TempDirDeletionStrategy}` you would like to use by\ndefault. Just like for strategies configured via the `deletionStrategy` attribute of the\n`@TempDir` annotation, the supplied class has to implement the `{TempDirDeletionStrategy}`\ninterface. The default strategy will be used for all `@TempDir` annotations unless the\n`deletionStrategy` attribute of the annotation specifies a different strategy.\n\nIn summary, the deletion strategy for a temporary directory is determined according to the\nfollowing precedence rules:\n\n1. The `deletionStrategy` attribute of the `@TempDir` annotation, if present\n2. The default `{TempDirDeletionStrategy}` configured via the configuration parameter,\nif present\n3. Otherwise, `org.junit.jupiter.api.io.TempDirDeletionStrategy$Standard` will be used.\n\n[[AutoClose]]\n== The @AutoClose Extension\n\nThe `{AutoCloseExtension}` automatically closes resources associated with fields.\nIt is registered by default. To use it, annotate a field in a test class with\n`{AutoClose}`.\n\n`@AutoClose` fields may be either `static` or non-static. If the value of an `@AutoClose`\nfield is `null` when it is evaluated the field will be ignored, but a warning message will\nbe logged to inform you.\n\nBy default, `@AutoClose` expects the value of the annotated field to implement a `close()`\nmethod that will be invoked to close the resource. However, developers can customize the\nname of the close method via the `value` attribute. For example, `@AutoClose(\"shutdown\")`\ninstructs JUnit to look for a `shutdown()` method to close the resource.\n\n`@AutoClose` fields are inherited from superclasses. Furthermore, `@AutoClose` fields from\nsubclasses will be closed before `@AutoClose` fields in superclasses.\n\nWhen multiple `@AutoClose` fields exist within a given test class, the order in which the\nresources are closed depends on an algorithm that is deterministic but intentionally\nnonobvious. This ensures that subsequent runs of a test suite close resources in the same\norder, thereby allowing for repeatable builds.\n\nThe `AutoCloseExtension` implements the `AfterAllCallback` and\n`TestInstancePreDestroyCallback` extension APIs. Consequently, a `static` `@AutoClose`\nfield will be closed after all tests in the current test class have completed, effectively\nafter `@AfterAll` methods have executed for the test class. A non-static `@AutoClose`\nfield will be closed before the current test class instance is destroyed. Specifically, if\nthe test class is configured with `@TestInstance(Lifecycle.PER_METHOD)` semantics, a\nnon-static `@AutoClose` field will be closed after the execution of each test method, test\nfactory method, or test template method. However, if the test class is configured with\n`@TestInstance(Lifecycle.PER_CLASS)` semantics, a non-static `@AutoClose` field will not\nbe closed until the current test class instance is no longer needed, which means after\n`@AfterAll` methods and after all `static` `@AutoClose` fields have been closed.\n\nThe following example demonstrates how to annotate an instance field with `@AutoClose` so\nthat the resource is automatically closed after test execution. In this example, we assume\nthat the default `@TestInstance(Lifecycle.PER_METHOD)` semantics apply.\n\n.A test class using `@AutoClose` to close a resource\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/AutoCloseDemo.java[tags=user_guide_example]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/AutoCloseDemo.kt[tags=user_guide_example]\n----\n--\n====\n<1> Annotate an instance field with `@AutoClose`.\n<2> `WebClient` implements `java.lang.AutoCloseable` which defines a `close()` method that\n will be invoked after each `@Test` method.\n\n[[DefaultLocaleAndTimeZone]]\n== The @DefaultLocale and @DefaultTimeZone Extensions\n\nThe `{DefaultLocale}` and `{DefaultTimeZone}` annotations can be used to change the values\nreturned from `Locale.getDefault()` and `TimeZone.getDefault()`, respectively, which are\noften used implicitly when no specific locale or time zone is chosen. Both annotations\nwork on the test class level and on the test method level, and are inherited from\nhigher-level containers. After the annotated element has been executed, the initial\ndefault value is restored.\n\n[[DefaultLocale]]\n=== @DefaultLocale\n\nThe default `Locale` can be specified using an\n{jdk-javadoc-base-url}/java.base/java/util/Locale.html#forLanguageTag-java.lang.String-[IETF BCP 47 language tag string].\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/DefaultLocaleTimezoneExtensionDemo.java[tags=default_locale_language]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/DefaultLocaleTimezoneExtensionDemo.kt[tags=default_locale_language]\n----\n--\n====\n\nAlternatively, the default `Locale` can be created using the following attributes from\nwhich a {jdk-javadoc-base-url}/java.base/java/util/Locale.Builder.html[`Locale.Builder`]\ncan create an instance:\n\n* `language`\n* `language` and `country`\n* `language`, `country`, and `variant`\n\nNOTE: The variant needs to be a string which follows the\nhttps://www.rfc-editor.org/rfc/rfc5646.html[IETF BCP 47 / RFC 5646] syntax.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/DefaultLocaleTimezoneExtensionDemo.java[tag=default_locale_language_alternatives]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/DefaultLocaleTimezoneExtensionDemo.kt[tag=default_locale_language_alternatives]\n----\n--\n====\n\nMixing language tag configuration (via the annotation's `value` attribute) and\nattribute-based configuration will cause an exception to be thrown. Furthermore, a\n`variant` can only be specified if `country` is also specified. Otherwise, an exception\nwill be thrown.\n\nMethod-level `@DefaultLocale` configuration overrides class-level configuration.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/DefaultLocaleTimezoneExtensionDemo.java[tag=default_locale_class_level]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/DefaultLocaleTimezoneExtensionDemo.kt[tag=default_locale_class_level]\n----\n--\n====\n\nNOTE: With class-level configuration, the specified locale is set before and reset after\neach individual test in the annotated class.\n\nIf your use case is not covered, you can implement the `{LocaleProvider}` interface.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/DefaultLocaleTimezoneExtensionDemo.java[tag=default_locale_with_provider]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/DefaultLocaleTimezoneExtensionDemo.kt[tag=default_locale_with_provider]\n----\n--\n====\n\nNOTE: The provider implementation must have a no-args (or default) constructor.\n\n[[DefaultTimeZone]]\n=== @DefaultTimeZone\n\nThe default `TimeZone` is specified according to the\n{jdk-javadoc-base-url}/java.base/java/util/TimeZone.html#getTimeZone(java.lang.String)[TimeZone.getTimeZone(String)]\nmethod.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/DefaultLocaleTimezoneExtensionDemo.java[tag=default_timezone_zone]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/DefaultLocaleTimezoneExtensionDemo.kt[tag=default_timezone_zone]\n----\n--\n====\n\nMethod-level `@DefaultTimeZone` configuration overrides class-level configuration.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/DefaultLocaleTimezoneExtensionDemo.java[tag=default_timezone_class_level]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/DefaultLocaleTimezoneExtensionDemo.kt[tag=default_timezone_class_level]\n----\n--\n====\n\nNOTE: With class-level configuration, the specified time zone is set before and reset\nafter each individual test in the annotated class.\n\nIf your use case is not covered, you can implement the `{TimeZoneProvider}` interface.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/DefaultLocaleTimezoneExtensionDemo.java[tag=default_time_zone_with_provider]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/DefaultLocaleTimezoneExtensionDemo.kt[tag=default_time_zone_with_provider]\n----\n--\n====\n\nNOTE: The provider implementation must have a no-args (or default) constructor.\n\n=== Thread Safety\n\nSince the default locale and time zone are global state, reading and writing them during\nxref:writing-tests/parallel-execution.adoc[parallel test execution] can lead to unpredictable\nresults and flaky tests. The `@DefaultLocale` and `@DefaultTimeZone` extensions are\nprepared for that and tests annotated with them will never execute in parallel (thanks to\n`{ResourceLock}`) to guarantee correct test results.\n\nHowever, this does not cover all possible cases. Tested code that reads or writes the\ndefault locale or time zone _independently_ of the extensions can still run in parallel\nand may thus behave erratically when, for example, such code unexpectedly reads a locale\nset by the extension in another thread. Consequently, tests that cover code that reads or\nwrites the default locale or time zone need to be annotated with one of the following\nrespective annotations.\n\n* `{ReadsDefaultLocale}`\n* `{ReadsDefaultTimeZone}`\n* `{WritesDefaultLocale}`\n* `{WritesDefaultTimeZone}`\n\nTests annotated with one of the above annotations will never execute in parallel with\ntests annotated with `@DefaultLocale` or `@DefaultTimeZone`.\n\n[[system-properties]]\n== The System Properties Extension\n\nThe system properties extension supports a set of annotations that work together to clear,\nset, and restore JVM system properties.\n\n[[system-properties-clear-and-set]]\n=== @ClearSystemProperty and @SetSystemProperty\n\nThe `{ClearSystemProperty}` and `{SetSystemProperty}` annotations can be used to clear and\nset, respectively, the values of JVM system properties for test execution. Both\nannotations work on the test method and class level and are repeatable, combinable, and\ninherited from higher-level containers. After the annotated method has been executed, the\nproperties configured in the annotation will be restored to their original value or the\nvalue of the higher-level container, or will be cleared if they did not previously have a\nvalue. Other system properties that are changed during the test are _not_ restored (unless\nrestoration is <> via\n`{RestoreSystemProperties}`).\n\nFor example, clearing a system property for test execution can be done as follows.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/SystemPropertyExtensionDemo.java[tag=systemproperty_clear_simple]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/SystemPropertyExtensionDemo.kt[tag=systemproperty_clear_simple]\n----\n--\n====\n\nThe following demonstrates how to set a system property for test execution.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/SystemPropertyExtensionDemo.java[tag=systemproperty_set_simple]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/SystemPropertyExtensionDemo.kt[tag=systemproperty_set_simple]\n----\n--\n====\n\nAs mentioned before, both annotations are repeatable, and they can also be combined.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/SystemPropertyExtensionDemo.java[tag=systemproperty_using_set_and_clear]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/SystemPropertyExtensionDemo.kt[tag=systemproperty_using_set_and_clear]\n----\n--\n====\n\nNote that class-level configuration is overridden by method-level configuration.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/SystemPropertyExtensionDemo.java[tag=systemproperty_using_at_class_level]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/SystemPropertyExtensionDemo.kt[tag=systemproperty_using_at_class_level]\n----\n--\n====\n\n[NOTE]\n====\nMethod-level configuration is visible in both `@BeforeEach` methods and `@AfterEach`\nmethods (see\nxref:extensions/relative-execution-order-of-user-code-and-extensions.adoc#overview[user\ncode and extension code execution order]).\n\nWith class-level configuration, the specified system properties are cleared or set before\nand reset after each individual test in the annotated class.\n====\n\n[[system-properties-restore]]\n=== @RestoreSystemProperties\n\nThe `{RestoreSystemProperties}` annotation can be used to restore changes to system\nproperties made directly in the test or in the code being tested. Although\n`@ClearSystemProperty` and `@SetSystemProperty` clear or set properties and values that\nare statically declared, they do not allow property values to be calculated dynamically.\nThus, there are times you may want to directly set properties in your test code.\n`@RestoreSystemProperties` can be placed on test methods or test classes and will\ncompletely restore all system properties to their original state after the test or test\nclass has finished.\n\n[NOTE]\n====\nDuring the execution of the annotated scope, the JVM system properties are set to a clone\nof the original `Properties` object. However, the clone does not include\n{jdk-javadoc-base-url}/java.base/java/util/Properties.html#defaults[the defaults] from the\noriginal.\n\nConsequently, the extension will perform a best effort attempt to detect default properties\nand fail if any were detected. For classes that extend `Properties` it is assumed that\n`clone()` is implemented with sufficient fidelity.\n====\n\nIn the following example, `@RestoreSystemProperties` is used on a test method, ensuring\nany changes made in that method are restored.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/SystemPropertyExtensionDemo.java[tag=systemproperty_restore_test]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/SystemPropertyExtensionDemo.kt[tag=systemproperty_restore_test]\n----\n--\n====\n\nWhen `@RestoreSystemProperties` is used on a test class, any changes to system properties\nduring the entire lifecycle of the test class, including test methods, `@BeforeAll`,\n`@BeforeEach`, and 'after' methods, are restored after the lifecycle of the test class is\ncomplete. In addition, the annotation is inherited by each test method just as if each one\nwere annotated with `@RestoreSystemProperties`.\n\nIn the following example, both test methods see the system property changes made in\n`@BeforeAll` and `@BeforeEach`; however, the test methods are isolated from each other\n(`isolatedTest2` does not _see_ changes made in `isolatedTest1`). As shown in the second\nexample below, the class-level `@RestoreSystemProperties` annotation ensures that system\nproperty changes made within the annotated class are completely restored after the class's\nlifecycle, ensuring that changes are not visible to `SomeOtherTestClass`. Note that\n`SomeOtherTestClass` uses the `@ReadsSystemProperty` annotation, which ensures that JUnit\ndoes not schedule the class to run during any test known to modify system properties (see\n<>).\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/SystemPropertyExtensionDemo.java[tag=systemproperty_class_restore_setup]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/SystemPropertyExtensionDemo.kt[tag=systemproperty_class_restore_setup]\n----\n--\n====\n\nSome other test class, running later:\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/SystemPropertyExtensionDemo.java[tag=systemproperty_class_restore_isolated_class]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/SystemPropertyExtensionDemo.kt[tag=systemproperty_class_restore_isolated_class]\n----\n--\n====\n\n[[system-properties-combined-usage]]\n=== Combining @ClearSystemProperty, @SetSystemProperty, and @RestoreSystemProperties\n\nThe three system property annotations can be combined, which can be useful when some\nsystem properties are set dynamically in code and others are not. For instance, imagine\nyou need to test an image generation utility that takes configuration from system\nproperties. Basic configuration can be specified declaratively using the `Clear` and `Set`\nannotations, and the image size could be set programmatically.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/SystemPropertyExtensionDemo.java[tag=systemproperty_method_combine_all_test]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/SystemPropertyExtensionDemo.kt[tag=systemproperty_method_combine_all_test]\n----\n--\n====\n\n[NOTE]\n====\nUsing `@RestoreSystemProperties` is not necessary to restore system properties modified\nvia `@ClearSystemProperty` or `@SetSystemProperty` since they both automatically restore\nthe referenced properties. `@RestoreSystemProperties` is only needed if system properties\nare modified during a test in some way _other than_ via the `Clear` and `Set` annotations.\n====\n\n[[system-properties-thread-safety]]\n=== Thread Safety\n\nSince system properties are global state, reading and writing them during\nxref:writing-tests/parallel-execution.adoc[parallel execution] can lead to unpredictable\nresults and flaky tests. The system property extension is prepared for that and tests\nannotated with `@ClearSystemProperty`, `@SetSystemProperty`, or `@RestoreSystemProperties`\nwill never execute in parallel (thanks to\nxref:writing-tests/parallel-execution.adoc#synchronization[resource locks]) to guarantee\ncorrect test results.\n\nHowever, this does not cover all possible cases. Tested code that reads or writes system\nproperties _independently_ of the extension can still run in parallel to it and may thus\nbehave erratically when, for example, it unexpectedly reads a property set by the\nextension in another thread. Tests that cover code that reads or writes system properties\nneed to be annotated with the respective annotation:\n\n* `{ReadsSystemProperty}`\n* `{WritesSystemProperty}` (though consider using `@RestoreSystemProperties` instead)\n\nTests annotated in this way will never execute in parallel with tests annotated with\n`@ClearSystemProperty`, `@SetSystemProperty`, or `@RestoreSystemProperties`.\n"
},
{
"path": "documentation/modules/ROOT/pages/writing-tests/class-templates.adoc",
"content": "= Class Templates\n\nA `{ClassTemplate}` is not a regular test class but rather a template for the contained\ntest cases. As such, it is designed to be invoked multiple times depending on invocation\ncontexts returned by the registered providers. Thus, it must be used in conjunction with a\nregistered `{ClassTemplateInvocationContextProvider}` extension.\nEach invocation of a class template behaves like the execution of a regular test class\nwith full support for the same lifecycle callbacks and extensions. Please refer to\nxref:extensions/providing-invocation-contexts-for-class-templates.adoc[] for usage examples.\n\nNOTE: xref:writing-tests/parameterized-classes-and-tests.adoc[Parameterized Classes] are a built-in\nspecialization of class templates.\n"
},
{
"path": "documentation/modules/ROOT/pages/writing-tests/conditional-test-execution.adoc",
"content": "= Conditional Test Execution\n\nThe xref:extensions/conditional-test-execution.adoc[`ExecutionCondition`] extension API in JUnit Jupiter allows\ndevelopers to either _enable_ or _disable_ a test class or test method based on certain\nconditions _programmatically_. The simplest example of such a condition is the built-in\n`{DisabledCondition}` which supports the `{Disabled}` annotation (see\nxref:writing-tests/disabling-tests.adoc[]).\n\nIn addition to `@Disabled`, JUnit Jupiter also supports several other annotation-based\nconditions in the `org.junit.jupiter.api.condition` package that allow developers to\nenable or disable test classes and test methods _declaratively_. If you wish to provide\ndetails about why they might be disabled, every annotation associated with these built-in\nconditions has a `disabledReason` attribute available for that purpose.\n\nWhen multiple `ExecutionCondition` extensions are registered, a test class or test method\nis disabled as soon as one of the conditions returns _disabled_. If a test class is\ndisabled, all test methods within that class are automatically disabled as well. If a test\nmethod is disabled, that prevents execution of the test method and method-level lifecycle\ncallbacks such as `@BeforeEach` methods, `@AfterEach` methods, and corresponding extension\nAPIs. However, that does not prevent the test class from being instantiated, and it does\nnot prevent the execution of class-level lifecycle callbacks such as `@BeforeAll` methods,\n`@AfterAll` methods, and corresponding extension APIs.\n\nSee xref:extensions/conditional-test-execution.adoc[`ExecutionCondition`] and the following sections for\ndetails.\n\n[TIP]\n.Composed Annotations\n====\nNote that any of the _conditional_ annotations listed in the following sections may also\nbe used as a meta-annotation in order to create a custom _composed annotation_. For\nexample, the `@TestOnMac` annotation in the\n<> shows how you can\ncombine `@Test` and `@EnabledOnOs` in a single, reusable annotation.\n====\n\n[NOTE]\n====\n_Conditional_ annotations in JUnit Jupiter are not `@Inherited`. Consequently, if you wish\nto apply the same semantics to subclasses, each conditional annotation must be redeclared\non each subclass.\n====\n\n[WARNING]\n====\nUnless otherwise stated, each of the _conditional_ annotations listed in the following\nsections can only be declared once on a given test interface, test class, or test method.\nIf a conditional annotation is directly present, indirectly present, or meta-present\nmultiple times on a given element, only the first such annotation discovered by JUnit will\nbe used; any additional declarations will be silently ignored. Note, however, that each\nconditional annotation may be used in conjunction with other conditional annotations in\nthe `org.junit.jupiter.api.condition` package.\n====\n\n[[os]]\n== Operating System and Architecture Conditions\n\nA container or test may be enabled or disabled on a particular operating system,\narchitecture, or combination of both via the `{EnabledOnOs}` and `{DisabledOnOs}`\nannotations.\n\n[[os-demo]]\n.Conditional execution based on operating system\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/ConditionalTestExecutionDemo.java[tags=user_guide_os]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/ConditionalTestExecutionDemo.kt[tags=user_guide_os]\n----\n--\n====\n\n[[architectures-demo]]\n.Conditional execution based on architecture\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/ConditionalTestExecutionDemo.java[tags=user_guide_architecture]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/ConditionalTestExecutionDemo.kt[tags=user_guide_architecture]\n----\n--\n====\n\n[[jre]]\n== Java Runtime Environment Conditions\n\nA container or test may be enabled or disabled on particular versions of the Java Runtime\nEnvironment (JRE) via the `{EnabledOnJre}` and `{DisabledOnJre}` annotations or on a\nparticular range of versions of the JRE via the `{EnabledForJreRange}` and\n`{DisabledForJreRange}` annotations. The range effectively defaults to `JRE.JAVA_8` as the\nlower bound and `JRE.OTHER` as the upper bound, which allows usage of half open ranges.\n\nThe following listing demonstrates the use of these annotations with predefined {JRE} enum\nconstants.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/ConditionalTestExecutionDemo.java[tags=user_guide_jre]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/ConditionalTestExecutionDemo.kt[tags=user_guide_jre]\n----\n--\n====\n\nSince the enum constants defined in {JRE} are static for any given JUnit release, you\nmight find that you need to configure a Java version that is not supported by the `JRE`\nenum. For example, when JUnit Jupiter 5.12 was released the `JRE` enum defined `JAVA_25`\nas the highest supported Java version. However, you may wish to run your tests against\nlater versions of Java. To support such use cases, you can specify arbitrary Java versions\nvia the `versions` attributes in `@EnabledOnJre` and `@DisabledOnJre` and via the\n`minVersion` and `maxVersion` attributes in `@EnabledForJreRange` and\n`@DisabledForJreRange`.\n\nThe following listing demonstrates the use of these annotations with arbitrary Java\nversions.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/ConditionalTestExecutionDemo.java[tags=user_guide_jre_arbitrary_versions]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/ConditionalTestExecutionDemo.kt[tags=user_guide_jre_arbitrary_versions]\n----\n--\n====\n\n[[native]]\n== Native Image Conditions\n\nA container or test may be enabled or disabled within a\nhttps://www.graalvm.org/reference-manual/native-image/[GraalVM native image] via the\n`{EnabledInNativeImage}` and `{DisabledInNativeImage}` annotations. These annotations are\ntypically used when running tests within a native image using the Gradle and Maven\nplug-ins from the GraalVM https://graalvm.github.io/native-build-tools/latest/[Native\nBuild Tools] project.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/ConditionalTestExecutionDemo.java[tags=user_guide_native]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/ConditionalTestExecutionDemo.kt[tags=user_guide_native]\n----\n--\n====\n\n[[system-properties]]\n== System Property Conditions\n\nA container or test may be enabled or disabled based on the value of the `named` JVM\nsystem property via the `{EnabledIfSystemProperty}` and `{DisabledIfSystemProperty}`\nannotations. The value supplied via the `matches` attribute will be interpreted as a\nregular expression.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/ConditionalTestExecutionDemo.java[tags=user_guide_system_property]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/ConditionalTestExecutionDemo.kt[tags=user_guide_system_property]\n----\n--\n====\n\n[TIP]\n====\n`{EnabledIfSystemProperty}` and `{DisabledIfSystemProperty}` are _repeatable annotations_.\nConsequently, these annotations may be declared multiple times on a test interface, test\nclass, or test method. Specifically, these annotations will be found if they are directly\npresent, indirectly present, or meta-present on a given element.\n====\n\n[[environment-variables]]\n== Environment Variable Conditions\n\nA container or test may be enabled or disabled based on the value of the `named`\nenvironment variable from the underlying operating system via the\n`{EnabledIfEnvironmentVariable}` and `{DisabledIfEnvironmentVariable}` annotations. The\nvalue supplied via the `matches` attribute will be interpreted as a regular expression.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/ConditionalTestExecutionDemo.java[tags=user_guide_environment_variable]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/ConditionalTestExecutionDemo.kt[tags=user_guide_environment_variable]\n----\n--\n====\n\n[TIP]\n====\n`{EnabledIfEnvironmentVariable}` and `{DisabledIfEnvironmentVariable}` are _repeatable\nannotations_. Consequently, these annotations may be declared multiple times on a test\ninterface, test class, or test method. Specifically, these annotations will be found if\nthey are directly present, indirectly present, or meta-present on a given element.\n====\n\n[[custom]]\n== Custom Conditions\n\nAs an alternative to implementing an xref:extensions/conditional-test-execution.adoc[`ExecutionCondition`], a\ncontainer or test may be enabled or disabled based on a _condition method_ configured via\nthe `{EnabledIf}` and `{DisabledIf}` annotations. A condition method must have a `boolean`\nreturn type and may accept either no arguments or a single `ExtensionContext` argument.\n\nThe following test class demonstrates how to configure a local method named\n`customCondition` via `@EnabledIf` and `@DisabledIf`.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/ConditionalTestExecutionDemo.java[tags=user_guide_custom]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/ConditionalTestExecutionDemo.kt[tags=user_guide_custom]\n----\n--\n====\n\nAlternatively, the condition method can be located outside the test class. In this case,\nit must be referenced by its _fully qualified name_ as demonstrated in the following\nexample.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\npackage example;\n\ninclude::example$java/example/ExternalCustomConditionDemo.java[tags=user_guide_external_custom_condition]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\npackage example.kotlin\n\ninclude::example$kotlin/example/kotlin/ExternalCustomConditionDemo.kt[tags=user_guide_external_custom_condition]\n----\n--\n====\n\n[NOTE]\n====\nThere are several cases where a condition method would need to be `static`:\n\n- when `@EnabledIf` or `@DisabledIf` is used at class level\n- when `@EnabledIf` or `@DisabledIf` is used on a `@ParameterizedTest` or a\n `@TestTemplate` method\n- when the condition method is located in an external class\n\nIn any other case, you can use either static methods or instance methods as condition\nmethods.\n====\n\n[TIP]\n====\nIt is often the case that you can use an existing static method in a utility class as a\ncustom condition.\n\nFor example, `java.awt.GraphicsEnvironment` provides a `public static boolean isHeadless()`\nmethod that can be used to determine if the current environment does not support a\ngraphical display. Thus, if you have a test that depends on graphical support you can\ndisable it when such support is unavailable as follows.\n\n[tabs]\n======\nJava::\n+\n--\n[source,java,indent=0]\n----\n@DisabledIf(value = \"java.awt.GraphicsEnvironment#isHeadless\",\n\tdisabledReason = \"headless environment\")\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\n@DisabledIf(value = \"java.awt.GraphicsEnvironment#isHeadless\",\n disabledReason = \"headless environment\")\n----\n--\n======\n====\n"
},
{
"path": "documentation/modules/ROOT/pages/writing-tests/definitions.adoc",
"content": "= Definitions\n\n== Platform Concepts\n\nContainer::\na node in the test tree that contains other containers or tests as its children (e.g. a _test class_).\n\nTest::\na node in the test tree that verifies expected behavior when executed (e.g. a `@Test` method).\n\n== Jupiter Concepts\n\nLifecycle Method::\nany method that is directly annotated or meta-annotated with\n`@BeforeAll`, `@AfterAll`, `@BeforeEach`, or `@AfterEach`.\n\nTest Class::\nany top-level class, `static` member class, or xref:writing-tests/nested-tests.adoc[`@Nested` class] that contains at least one _test method_, i.e. a _container_.\nTest classes must not be `abstract` and must have a single constructor.\nJava `record` classes are supported as well.\n\nTest Method::\nany instance method that is directly annotated or meta-annotated with\n`@Test`, `@RepeatedTest`, `@ParameterizedTest`, `@TestFactory`, or `@TestTemplate`.\nWith the exception of `@Test`, these create a _container_ in the test tree that groups\n_tests_ or, potentially (for `@TestFactory`), other _containers_.\n"
},
{
"path": "documentation/modules/ROOT/pages/writing-tests/dependency-injection-for-constructors-and-methods.adoc",
"content": "= Dependency Injection for Constructors and Methods\n\nIn JUnit Jupiter, both test constructors and methods are permitted to have parameters.\nThis allows for greater flexibility and enables _Dependency Injection_ for constructors\nand methods.\n\n`{ParameterResolver}` defines the API for test extensions that wish to _dynamically_\nresolve parameters at runtime. If a _test class_ constructor, a _test method_, or a\n_lifecycle method_ (see xref:writing-tests/definitions.adoc[]) accepts a parameter, the parameter\nmust be resolved at runtime by a registered `ParameterResolver`.\n\n[[built-in-parameter-resolvers]]\n== Built-In Parameter Resolvers\n\nThere are currently three built-in resolvers that are registered automatically.\n\n[[test-info]]\n=== TestInfo\n\nIf a constructor or method parameter is of type `{TestInfo}`, the\n`{TestInfoParameterResolver}` will supply an instance of `TestInfo` corresponding to the\ncurrent container or test as the value for the parameter. The `TestInfo` can then be used\nto retrieve information about the current container or test such as the display name, the\ntest class, the test method, and associated tags. The display name is either a technical\nname, such as the name of the test class or test method, or a custom name configured via\n`@DisplayName`.\n\n`{TestInfo}` acts as a drop-in replacement for the `TestName` rule from JUnit 4. The\nfollowing demonstrates how to have `TestInfo` injected into a `@BeforeAll` method, test\nclass constructor, `@BeforeEach` method, and `@Test` method.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/TestInfoDemo.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/TestInfoDemo.kt[tags=user_guide]\n----\n--\n====\n\n[[repetition-info]]\n=== RepetitionInfo\n\nIf a method parameter in a `@RepeatedTest`, `@BeforeEach`, or `@AfterEach` method is of\ntype `{RepetitionInfo}`, the `{RepetitionExtension}` will supply an instance of\n`RepetitionInfo`. `RepetitionInfo` can then be used to retrieve information about the\ncurrent repetition, the total number of repetitions, the number of repetitions that have\nfailed, and the failure threshold for the corresponding `@RepeatedTest`. Note, however,\nthat `RepetitionExtension` is not registered outside the context of a `@RepeatedTest`. See\nxref:writing-tests/repeated-tests.adoc#examples[Repeated Test Examples].\n\n[[test-reporter]]\n=== TestReporter\n\nIf a constructor or method parameter is of type `{TestReporter}`, the\n`{TestReporterParameterResolver}` will supply an instance of `TestReporter`. The\n`TestReporter` can be used to publish additional data about the current test run or attach\nfiles to it. The data can be consumed in a `{TestExecutionListener}` via the\n`reportingEntryPublished()` or `fileEntryPublished()` method, respectively. This allows\nthem to be viewed in IDEs or included in reports.\n\nIn JUnit Jupiter you should use `TestReporter` where you used to print information to\n`stdout` or `stderr` in JUnit 4. Some IDEs print report entries to `stdout` or display\nthem in the user interface for test results.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/TestReporterDemo.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/TestReporterDemo.kt[tags=user_guide]\n----\n--\n====\n\n[[custom-parameter-resolvers]]\n== Custom Parameter Resolvers\n\nNOTE: Custom parameter resolvers must be explicitly enabled by\nxref:extensions/registering-extensions.adoc[registering] appropriate\nxref:extensions/overview.adoc[extensions].\n\nCheck out the `xref:extensions/registering-extensions.adoc#RandomNumberExtension[RandomNumberExtension]`\nfor an example of a custom `{ParameterResolver}`. While not intended to be production-ready,\nit demonstrates the simplicity and expressiveness of both the extension model and the\nparameter resolution process. `MyRandomParametersTest` demonstrates how to inject random\nvalues into a constructor and a `@Test` method.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/MyRandomParametersTest.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/MyRandomParametersTest.kt[tags=user_guide]\n----\n--\n====\n\nFor real-world use cases, check out the source code for the `{MockitoExtension}` and the\n`{SpringExtension}`.\n\nWhen the type of the parameter to inject is the only condition for your\n`{ParameterResolver}`, you can use the generic `{TypeBasedParameterResolver}` base class.\nThe `supportsParameters` method is implemented behind the scenes and supports\nparameterized types.\n"
},
{
"path": "documentation/modules/ROOT/pages/writing-tests/disabling-tests.adoc",
"content": "= Disabling Tests\n\nEntire test classes or individual test methods may be _disabled_ via the `{Disabled}`\nannotation, via one of the annotations discussed in\nxref:writing-tests/conditional-test-execution.adoc[], or via a custom xref:extensions/conditional-test-execution.adoc[`ExecutionCondition`].\n\nWhen `@Disabled` is applied at the class level, all test methods within that class are\nautomatically disabled as well.\n\nIf a test method is disabled via `@Disabled`, that prevents execution of the test method\nand method-level lifecycle callbacks such as `@BeforeEach` methods, `@AfterEach` methods,\nand corresponding extension APIs. However, that does not prevent the test class from being\ninstantiated, and it does not prevent the execution of class-level lifecycle callbacks\nsuch as `@BeforeAll` methods, `@AfterAll` methods, and corresponding extension APIs.\n\nHere's a `@Disabled` test class.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/DisabledClassDemo.java[tags=user_guide]\n----\n\nAnd here's a test class that contains a `@Disabled` test method.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/DisabledTestsDemo.java[tags=user_guide]\n----\n\n[TIP]\n====\n`@Disabled` may be declared without providing a _reason_; however, the JUnit team\nrecommends that developers provide a short explanation for why a test class or test\nmethod has been disabled. Consequently, the above examples both show the use of a reason\n-- for example, `@Disabled(\"Disabled until bug #42 has been resolved\")`. Some development\nteams even require the presence of issue tracking numbers in the _reason_ for automated\ntraceability, etc.\n====\n\n[NOTE]\n====\n`@Disabled` is not `@Inherited`. Consequently, if you wish to disable a class whose\nsuperclass is `@Disabled`, you must redeclare `@Disabled` on the subclass.\n====\n"
},
{
"path": "documentation/modules/ROOT/pages/writing-tests/display-names.adoc",
"content": "= Display Names\n\nTest classes and test methods can declare custom display names via `@DisplayName` -- with\nspaces, special characters, and even emojis -- that will be displayed in test reports and\nby test runners and IDEs.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/DisplayNameDemo.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/DisplayNameDemo.kt[tags=user_guide]\n----\n--\n====\n\n[TIP]\n====\nIn Kotlin, you can use backtick-enclosed function names as an alternative to\n`@DisplayName` for simple display names:\n\n[source,kotlin,indent=0]\n----\n@Test\nfun `custom test name containing spaces`() {\n // will be displayed as \"custom test name containing spaces\"\n}\n----\n====\n\n[NOTE]\n====\nControl characters in text-based arguments in display names for parameterized tests are\nescaped by default. See xref:writing-tests/parameterized-classes-and-tests.adoc#display-names-quoted-text[Quoted Text-based Arguments]\nfor details.\n\nAny remaining ISO control characters in a display name will be replaced as follows.\n\n[cols=\"25%,15%,60%\"]\n|===\n| Original | Replacement | Description\n\n| ```\\r```\n| ``````\n| Textual representation of a carriage return\n\n| ```\\n```\n| ``````\n| Textual representation of a line feed\n\n| Other control character\n| ```�```\n| Unicode replacement character (U+FFFD)\n|===\n====\n\n[[generator]]\n== Display Name Generators\n\nJUnit Jupiter supports custom display name generators that can be configured via the\n`@DisplayNameGeneration` annotation.\n\nGenerators can be created by implementing the `DisplayNameGenerator` API. The following\ntable lists the default display name generators available in Jupiter.\n\n[cols=\"20,80\"]\n|===\n| DisplayNameGenerator | Behavior\n\n| `Standard` | Matches the standard display name generation behavior in place since JUnit Jupiter was introduced.\n| `Simple` | Extends the functionality of `Standard` by removing trailing parentheses for methods with no parameters.\n| `ReplaceUnderscores` | Replaces underscores with spaces.\n| `IndicativeSentences` | Generates complete sentences by concatenating the names of the test and the enclosing classes.\n|===\n\nNOTE: Values provided via `@DisplayName` annotations always take precedence over display\nnames generated by a `DisplayNameGenerator`.\n\n======\nThe following example demonstrates the use of the `ReplaceUnderscores` display name\ngenerator.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/DisplayNameGeneratorDemo.java[tags=user_guide_replace_underscores]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/DisplayNameGeneratorDemo.kt[tags=user_guide_replace_underscores]\n----\n--\n====\n\nRunning the above test class results in the following display names.\n\n```\nA year is not supported ✔\n├─ if it is zero ✔\n└─ A negative value for year is not supported by the leap year computation. ✔\n ├─ For example, year -1 is not supported. ✔\n └─ For example, year -4 is not supported. ✔\n```\n======\n\n======\nWith the `IndicativeSentences` display name generator, you can customize the separator and\nthe underlying generator by using `@IndicativeSentencesGeneration` as shown in the\nfollowing example.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/DisplayNameGeneratorDemo.java[tags=user_guide_indicative_sentences]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/DisplayNameGeneratorDemo.kt[tags=user_guide_indicative_sentences]\n----\n--\n====\n\nRunning the above test class results in the following display names.\n\n```\nA year is a leap year ✔\n├─ A year is a leap year -> if it is divisible by 4 but not by 100 ✔\n└─ A year is a leap year -> if it is one of the following years ✔\n ├─ Year 2016 is a leap year. ✔\n ├─ Year 2020 is a leap year. ✔\n └─ Year 2048 is a leap year. ✔\n```\n======\n\n======\nWith `IndicativeSentences`, you can optionally specify custom sentence fragments via the\n`@SentenceFragment` annotation as demonstrated in the following example.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/DisplayNameGeneratorDemo.java[tags=user_guide_custom_sentence_fragments]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/DisplayNameGeneratorDemo.kt[tags=user_guide_custom_sentence_fragments]\n----\n--\n====\n\nRunning the above test class results in the following display names.\n\n```\nA year is a leap year ✔\n├─ A year is a leap year, if it is divisible by 4 but not by 100 ✔\n└─ A year is a leap year, if it is one of the following years ✔\n ├─ 2016 ✔\n ├─ 2020 ✔\n └─ 2048 ✔\n```\n======\n\n\n[[generator-default]]\n== Setting the Default Display Name Generator\n\nYou can use the `junit.jupiter.displayname.generator.default`\nxref:running-tests/configuration-parameters.adoc[configuration parameter] to specify the fully qualified\nclass name of the `DisplayNameGenerator` you would like to use by default. Just like for\ndisplay name generators configured via the `@DisplayNameGeneration` annotation, the\nsupplied class has to implement the `DisplayNameGenerator` interface. The default display\nname generator will be used for all tests unless the `@DisplayNameGeneration` annotation\nis present on an enclosing test class or test interface. Values provided via\n`@DisplayName` annotations always take precedence over display names generated by a\n`DisplayNameGenerator`.\n\nFor example, to use the `ReplaceUnderscores` display name generator by default, you should\nset the configuration parameter to the corresponding fully qualified class name (e.g., in\n`src/test/resources/junit-platform.properties`):\n\n[source,properties,indent=0]\n----\njunit.jupiter.displayname.generator.default = \\\n org.junit.jupiter.api.DisplayNameGenerator$ReplaceUnderscores\n----\n\nSimilarly, you can specify the fully qualified name of any custom class that implements\n`DisplayNameGenerator`.\n\n[[generator-precedence-rules]]\nIn summary, the display name for a test class or method is determined according to the\nfollowing precedence rules:\n\n1. value of the `@DisplayName` annotation, if present\n2. by calling the `DisplayNameGenerator` specified in the `@DisplayNameGeneration`\n annotation, if present\n3. by calling the default `DisplayNameGenerator` configured via the configuration\n parameter, if present\n4. by calling `org.junit.jupiter.api.DisplayNameGenerator.Standard`\n"
},
{
"path": "documentation/modules/ROOT/pages/writing-tests/dynamic-tests.adoc",
"content": "= Dynamic Tests\n\nThe standard `@Test` annotation in JUnit Jupiter described in\nxref:writing-tests/annotations.adoc[] is very similar to the `@Test` annotation in JUnit 4. Both\ndescribe methods that implement test cases. These test cases are static in the sense that\nthey are fully specified at compile time, and their behavior cannot be changed by\nanything happening at runtime. _Assumptions provide a basic form of dynamic behavior but\nare intentionally rather limited in their expressiveness._\n\nIn addition to these standard tests a completely new kind of test programming model has\nbeen introduced in JUnit Jupiter. This new kind of test is a _dynamic test_ which is\ngenerated at runtime by a factory method that is annotated with `@TestFactory`.\n\nIn contrast to `@Test` methods, a `@TestFactory` method is not itself a test case but\nrather a factory for test cases. Thus, a dynamic test is the product of a factory.\nTechnically speaking, a `@TestFactory` method must return a single `DynamicNode` or a\n_stream_ of `DynamicNode` instances or any of its subclasses. In this context, a \"stream\"\nis anything that JUnit can reliably convert into a `Stream`, such as `Stream`,\n`Collection`, `Iterator`, `Iterable`, an array of objects, or any type that provides an\n`iterator(): Iterator` method (such as, for example, a `kotlin.sequences.Sequence`).\n\nInstantiable subclasses of `DynamicNode` are `DynamicContainer` and `DynamicTest`.\n`DynamicContainer` instances are composed of a _display name_ and a list of dynamic child\nnodes, enabling the creation of arbitrarily nested hierarchies of dynamic nodes.\n`DynamicTest` instances will be executed lazily, enabling dynamic and even\nnon-deterministic generation of test cases.\n\nAny `Stream` returned by a `@TestFactory` will be properly closed by calling\n`stream.close()`, making it safe to use a resource such as `Files.lines()`.\n\nAs with `@Test` methods, `@TestFactory` methods must not be `private` or `static` and may\noptionally declare parameters to be resolved by `ParameterResolvers`.\n\nA `DynamicTest` is a test case generated at runtime. It is composed of a _display name_\nand an `Executable`. `Executable` is a `@FunctionalInterface` which means that the\nimplementations of dynamic tests can be provided as _lambda expressions_ or _method\nreferences_.\n\n.Dynamic Test Lifecycle\nWARNING: The execution lifecycle of a dynamic test is quite different than it is for a\nstandard `@Test` case. Specifically, there are no lifecycle callbacks for individual\ndynamic tests. This means that `@BeforeEach` and `@AfterEach` methods and their\ncorresponding extension callbacks are executed for the `@TestFactory` method but not for\neach _dynamic test_. In other words, if you access fields from the test instance within a\nlambda expression for a dynamic test, those fields will not be reset by callback methods\nor extensions between the execution of individual dynamic tests generated by the same\n`@TestFactory` method.\n\n[[examples]]\n== Dynamic Test Examples\n\nThe following `DynamicTestsDemo` class demonstrates several examples of test factories\nand dynamic tests.\n\nThe first method returns an invalid return type and will cause a warning to be reported by\nJUnit during test discovery. Such methods are not executed.\n\nThe next six methods demonstrate the generation of a `Collection`, `Iterable`, `Iterator`,\narray, or `Stream` of `DynamicTest` instances. Most of these examples do not really\nexhibit dynamic behavior but merely demonstrate the supported return types in principle.\nHowever, `dynamicTestsFromStream()` and `dynamicTestsFromIntStream()` demonstrate how to\ngenerate dynamic tests for a given set of strings or a range of input numbers.\n\nThe next method is truly dynamic in nature. `generateRandomNumberOfTests()` implements an\n`Iterator` that generates random numbers, a display name generator, and a test executor\nand then provides all three to `DynamicTest.stream()`. Although the non-deterministic\nbehavior of `generateRandomNumberOfTests()` is of course in conflict with test\nrepeatability and should thus be used with care, it serves to demonstrate the\nexpressiveness and power of dynamic tests.\n\nThe next method is similar to `generateRandomNumberOfTests()` in terms of flexibility;\nhowever, `dynamicTestsFromStreamFactoryMethod()` generates a stream of dynamic tests from\nan existing `Stream` via the `DynamicTest.stream()` factory method.\n\nFor demonstration purposes, the `dynamicNodeSingleTest()` method generates a single\n`DynamicTest` instead of a stream, and the `dynamicNodeSingleContainer()` method generates\na nested hierarchy of dynamic tests utilizing `DynamicContainer`.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/DynamicTestsDemo.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/DynamicTestsDemo.kt[tags=user_guide]\n----\n--\n====\n\n[[named-support]]\n== Dynamic Tests and Named\n\nIn some cases, it can be more natural to specify inputs together with a descriptive name\nusing the {Named} API and the corresponding `stream()` factory methods on `DynamicTest` as\nshown in the first example below. The second example takes it one step further and allows\nto provide the code block that should be executed by implementing the `Executable`\ninterface along with `Named` via the `NamedExecutable` base class.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/DynamicTestsNamedDemo.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/DynamicTestsNamedDemo.kt[tags=user_guide]\n----\n--\n====\n\n[[uri-test-source]]\n== URI Test Sources for Dynamic Tests\n\nThe JUnit Platform provides `TestSource`, a representation of the source of a test or\ncontainer used to navigate to its location by IDEs and build tools.\n\nThe `TestSource` for a dynamic test or dynamic container can be constructed from a\n`java.net.URI` which can be supplied via the `DynamicTest.dynamicTest(String, URI,\nExecutable)` or `DynamicContainer.dynamicContainer(String, URI, Stream)` factory method,\nrespectively. The `URI` will be converted to one of the following `TestSource`\nimplementations.\n\n`ClasspathResourceSource` ::\n If the `URI` contains the `classpath` scheme -- for example,\n `classpath:/test/foo.xml?line=20,column=2`.\n\n`DirectorySource` ::\n If the `URI` represents a directory present in the file system.\n\n`FileSource` ::\n If the `URI` represents a file present in the file system.\n\n`MethodSource` ::\n If the `URI` contains the `method` scheme and the fully qualified method name (FQMN) --\n for example, `method:org.junit.Foo#bar(java.lang.String, java.lang.String[])`. Please\n refer to the Javadoc for `{DiscoverySelectors}.{DiscoverySelectors_selectMethod}` for the\n supported formats for a FQMN.\n\n`ClassSource` ::\n If the `URI` contains the `class` scheme and the fully qualified class name --\n for example, `class:org.junit.Foo?line=42`.\n\n`UriSource` ::\n If none of the above `TestSource` implementations are applicable.\n\n[[parallel-execution]]\n== Parallel Execution\n\nDynamic tests and containers support\nxref:writing-tests/parallel-execution.adoc[parallel execution]. You can configure their\n`ExecutionMode` by using the `dynamicTest(Consumer)` and `dynamicContainer(Consumer)`\nfactory methods as illustrated by the following example.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/DynamicTestsDemo.java[tags=execution_mode]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/DynamicTestsDemo.kt[tags=execution_mode]\n----\n--\n====\n\nExecuting the above test factory method results in the following test tree and execution\nmodes:\n\n* dynamicTestsWithConfiguredExecutionMode() -- `CONCURRENT` (from `@Execution` annotation)\n** Container A -- `CONCURRENT` (from `@Execution` annotation)\n*** not null -- `SAME_THREAD` (from `executionMode(...)` call)\n*** properties -- `CONCURRENT` (from `@Execution` annotation)\n**** length > 0 -- `CONCURRENT` (from `executionMode(...)` call)\n**** not empty -- `SAME_THREAD` (from `childExecutionMode(...)` call)\n** ... (same for \"Container B\" and \"Container C\")\n"
},
{
"path": "documentation/modules/ROOT/pages/writing-tests/exception-handling.adoc",
"content": "= Exception Handling\n\nJUnit Jupiter provides robust support for handling test exceptions. This includes the\nbuilt-in mechanisms for managing test failures due to exceptions, the role of exceptions\nin implementing assertions and assumptions, and how to specifically assert non-throwing\nconditions in code.\n\n[[uncaught]]\n== Uncaught Exceptions\n\nIn JUnit Jupiter, if an exception is thrown from a test method, a lifecycle method, or an\nextension and not caught within that test method, lifecycle method, or extension, the\nframework will mark the test or test class as failed.\n\n[TIP]\n====\nFailed assumptions deviate from this general rule.\n\nIn contrast to failed assertions, failed assumptions do not result in a test failure;\nrather, a failed assumption results in a test being aborted.\n\nSee xref:writing-tests/assumptions.adoc[] for further details and examples.\n====\n\nIn the following example, the `failsDueToUncaughtException()` method throws an\n`ArithmeticException`. Since the exception is not caught within the test method, JUnit\nJupiter will mark the test as failed.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/exception/UncaughtExceptionHandlingDemo.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/exception/UncaughtExceptionHandlingDemo.kt[tags=user_guide]\n----\n--\n====\n\nNOTE: It's important to note that specifying a `throws` clause in the test method has\nno effect on the outcome of the test. JUnit Jupiter does not interpret a `throws` clause\nas an expectation or assertion about what exceptions the test method should throw. A test\nfails only if an exception is thrown unexpectedly or if an assertion fails.\n\n[[failed-assertions]]\n== Failed Assertions\n\nAssertions in JUnit Jupiter are implemented using exceptions. The framework provides a set\nof assertion methods in the `org.junit.jupiter.api.Assertions` class, which throw\n`AssertionError` when an assertion fails. This mechanism is a core aspect of how JUnit\nhandles assertion failures as exceptions. See the xref:writing-tests/assertions.adoc[] section for\nfurther information about JUnit Jupiter's assertion support.\n\nNOTE: Third-party assertion libraries may choose to throw an `AssertionError` to signal a\nfailed assertion; however, they may also choose to throw different types of exceptions to\nsignal failures. See also: xref:writing-tests/assertions.adoc#third-party[Third-party Assertion Libraries].\n\nTIP: JUnit Jupiter itself does not differentiate between failed assertions\n(`AssertionError`) and other types of exceptions. All uncaught exceptions lead to a test\nfailure. However, Integrated Development Environments (IDEs) and other tools may\ndistinguish between these two types of failures by checking whether the thrown exception\nis an instance of `AssertionError`.\n\nIn the following example, the `failsDueToUncaughtAssertionError()` method throws an\n`AssertionError`. Since the exception is not caught within the test method, JUnit Jupiter\nwill mark the test as failed.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/exception/FailedAssertionDemo.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/exception/FailedAssertionDemo.kt[tags=user_guide]\n----\n--\n====\n\n[[expected]]\n== Asserting Expected Exceptions\n\nJUnit Jupiter offers specialized assertions for testing that specific exceptions are\nthrown under expected conditions. The `assertThrows()` and `assertThrowsExactly()`\nassertions are critical tools for validating that your code responds correctly to error\nconditions by throwing the appropriate exceptions.\n\n[[expected-assertThrows]]\n=== Using `assertThrows()`\n\nThe `assertThrows()` method is used to verify that a particular type of exception is\nthrown during the execution of a provided executable block. It not only checks for the\ntype of the thrown exception but also its subclasses, making it suitable for more\ngeneralized exception handling tests. The `assertThrows()` assertion method returns the\nthrown exception object to allow performing additional assertions on it.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/exception/ExceptionAssertionDemo.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/exception/ExceptionAssertionDemo.kt[tags=user_guide]\n----\n--\n====\n\n[[expected-assertThrowsExactly]]\n=== Using `assertThrowsExactly()`\n\nThe `assertThrowsExactly()` method is used when you need to assert that the exception\nthrown is exactly of a specific type, not allowing for subclasses of the expected\nexception type. This is useful when precise exception handling behavior needs to be\nvalidated. Similar to `assertThrows()`, the `assertThrowsExactly()` assertion method also\nreturns the thrown exception object to allow performing additional assertions on it.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/exception/ExceptionAssertionExactDemo.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/exception/ExceptionAssertionExactDemo.kt[tags=user_guide]\n----\n--\n====\n\n[[not-expected]]\n== Asserting That no Exception is Expected\n\nAlthough any exception thrown from a test method will cause the test to fail, there are\ncertain use cases where it can be beneficial to explicitly assert that an exception is\n_not_ thrown for a given code block within a test method. The `assertDoesNotThrow()`\nassertion can be used when you want to verify that a particular piece of code does not\nthrow any exceptions.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/exception/AssertDoesNotThrowExceptionDemo.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/exception/AssertDoesNotThrowExceptionDemo.kt[tags=user_guide]\n----\n--\n====\n\nNOTE: Third-party assertion libraries often provide similar support. For example, AssertJ\nhas `assertThatNoException().isThrownBy(() -> ...)`. See also:\nxref:writing-tests/assertions.adoc#third-party[Third-party Assertion Libraries].\n"
},
{
"path": "documentation/modules/ROOT/pages/writing-tests/intro.adoc",
"content": "= Writing Tests\n\nThe following example provides a glimpse at the minimum requirements for writing a test in\nJUnit Jupiter. Subsequent sections of this chapter will provide further details on all\navailable features.\n\n.A first test case\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/MyFirstJUnitJupiterTests.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/MyFirstJUnitJupiterTests.kt[tags=user_guide]\n----\n--\n====\n"
},
{
"path": "documentation/modules/ROOT/pages/writing-tests/nested-tests.adoc",
"content": "= Nested Tests\n\n`@Nested` tests give the test writer more capabilities to express the relationship among\nseveral groups of tests. Such nested tests make use of Java's nested classes and\nfacilitate hierarchical thinking about the test structure. Here's an elaborate example,\nboth as source code and as a screenshot of the execution within an IDE.\n\n.Nested test suite for testing a stack\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/TestingAStackDemo.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/TestingAStackDemo.kt[tags=user_guide]\n----\n--\n====\n\nWhen executing this example in an IDE, the test execution tree in the GUI will look\nsimilar to the following image.\n\nimage::writing-tests_nested_test_ide.png[caption='',title='Executing a nested test in an IDE']\n\nIn this example, preconditions from outer tests are used in inner tests by defining\nhierarchical lifecycle methods for the setup code. For example, `createNewStack()` is a\n`@BeforeEach` lifecycle method that is used in the test class in which it is defined and\nin all levels in the nesting tree below the class in which it is defined.\n\nThe fact that setup code from outer tests is run before inner tests are executed gives you\nthe ability to run all tests independently. You can even run inner tests alone without\nrunning the outer tests, because the setup code from the outer tests is always executed.\n\nNOTE: _Only non-static nested classes_ (i.e. _inner classes_) can serve as `@Nested` test\nclasses. Nesting can be arbitrarily deep, and those inner classes are subject to full\nlifecycle support, including `@BeforeAll` and `@AfterAll` methods on each level.\n\n[[interoperability]]\n== Interoperability\n\n`@Nested` may be combined with\nxref:writing-tests/parameterized-classes-and-tests.adoc[`@ParameterizedClass`] in which case the nested test\nclass is parameterized.\n\nThe following example illustrates how to combine `@Nested` with `@ParameterizedClass` and\n`@ParameterizedTest`.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedClassDemo.java[tags=nested]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/ParameterizedClassDemo.kt[tags=nested]\n----\n--\n====\n\nExecuting the above test class yields the following output:\n\n....\nFruitTests ✔\n├─ [1] fruit = \"apple\" ✔\n│ └─ QuantityTests ✔\n│ ├─ [1] quantity = 23 ✔\n│ │ └─ test(Duration) ✔\n│ │ ├─ [1] duration = \"PT1H\" ✔\n│ │ └─ [2] duration = \"PT2H\" ✔\n│ └─ [2] quantity = 42 ✔\n│ └─ test(Duration) ✔\n│ ├─ [1] duration = \"PT1H\" ✔\n│ └─ [2] duration = \"PT2H\" ✔\n└─ [2] fruit = \"banana\" ✔\n └─ QuantityTests ✔\n ├─ [1] quantity = 23 ✔\n │ └─ test(Duration) ✔\n │ ├─ [1] duration = \"PT1H\" ✔\n │ └─ [2] duration = \"PT2H\" ✔\n └─ [2] quantity = 42 ✔\n └─ test(Duration) ✔\n ├─ [1] duration = \"PT1H\" ✔\n └─ [2] duration = \"PT2H\" ✔\n....\n"
},
{
"path": "documentation/modules/ROOT/pages/writing-tests/parallel-execution.adoc",
"content": "= Parallel Execution\n\nBy default, JUnit Jupiter tests are run sequentially in a single thread; however, running\ntests in parallel -- for example, to speed up execution -- is available as an opt-in\nfeature. To enable parallel execution, set the `junit.jupiter.execution.parallel.enabled`\nconfiguration parameter to `true` -- for example, in `junit-platform.properties` (see\nxref:running-tests/configuration-parameters.adoc[] for other options).\n\nPlease note that enabling this property is only the first step required to execute tests\nin parallel. If enabled, test classes and methods will still be executed sequentially by\ndefault. Whether or not a node in the test tree is executed concurrently is controlled by\nits execution mode. The following two modes are available.\n\n`SAME_THREAD`::\n Force execution in the same thread used by the parent. For example, when used on a test\n method, the test method will be executed in the same thread as any `@BeforeAll` or\n `@AfterAll` methods of the containing test class.\n\n`CONCURRENT`::\n Execute concurrently unless a resource lock forces execution in the same thread.\n\nBy default, nodes in the test tree use the `SAME_THREAD` execution mode. You can change\nthe default by setting the `junit.jupiter.execution.parallel.mode.default` configuration\nparameter. Alternatively, you can use the `{Execution}` annotation to change the\nexecution mode for the annotated element and its subelements (if any) which allows you to\nactivate parallel execution for individual test classes, one by one.\n\n[source,properties]\n.Configuration parameters to execute all tests in parallel\n----\njunit.jupiter.execution.parallel.enabled = true\njunit.jupiter.execution.parallel.mode.default = concurrent\n----\n\nThe default execution mode is applied to all nodes of the test tree with a few notable\nexceptions, namely test classes that use the `Lifecycle.PER_CLASS` mode or a\n`{MethodOrderer}`. In the former case, test authors have to ensure that the test class is\nthread-safe; in the latter, concurrent execution might conflict with the configured\nexecution order. Thus, in both cases, test methods in such test classes are only executed\nconcurrently if the `@Execution(CONCURRENT)` annotation is present on the test class or\nmethod.\n\nYou can use the `@Execution` annotation to explicitly configure the execution mode for a\ntest class or method:\n\n[source,java]\n----\ninclude::example$java/example/ExplicitExecutionModeDemo.java[tags=user_guide]\n----\n\nThis allows test classes or methods to opt in or out of concurrent execution regardless of\nthe globally configured default.\n\nWhen parallel execution is enabled and a default `{ClassOrderer}` is registered (see\nxref:writing-tests/test-execution-order.adoc#classes[Class Order] for details), top-level test classes will\ninitially be sorted accordingly and scheduled in that order. However, they are not\nguaranteed to be started in exactly that order since the threads they are executed on are\nnot controlled directly by JUnit.\n\nAll nodes of the test tree that are configured with the `CONCURRENT` execution mode will\nbe executed fully in parallel according to the provided\n<> while observing the\ndeclarative <>\nmechanism. Please note that xref:running-tests/capturing-standard-output-error.adoc[] needs to be enabled\nseparately.\n\nIn addition, you can configure the default execution mode for top-level classes by setting\nthe `junit.jupiter.execution.parallel.mode.classes.default` configuration parameter. By\ncombining both configuration parameters, you can configure classes to run in parallel but\ntheir methods in the same thread:\n\n[source,properties]\n.Configuration parameters to execute top-level classes in parallel but methods in same thread\n----\njunit.jupiter.execution.parallel.enabled = true\njunit.jupiter.execution.parallel.mode.default = same_thread\njunit.jupiter.execution.parallel.mode.classes.default = concurrent\n----\n\nThe opposite combination will run all methods within one class in parallel, but top-level\nclasses will run sequentially:\n\n[source,properties]\n.Configuration parameters to execute top-level classes sequentially but their methods in parallel\n----\njunit.jupiter.execution.parallel.enabled = true\njunit.jupiter.execution.parallel.mode.default = concurrent\njunit.jupiter.execution.parallel.mode.classes.default = same_thread\n----\n\nThe following diagram illustrates how the execution of two top-level test classes `A` and\n`B` with two test methods per class behaves for all four combinations of\n`junit.jupiter.execution.parallel.mode.default` and\n`junit.jupiter.execution.parallel.mode.classes.default` (see labels in first column).\n\n////\nSource: https://mermaid-js.github.io/mermaid-live-editor/edit#pako:eNqFlE1u2zAQha9CEChio7IQKfVGXfUH_QEatICyKAIBwYQaW0QkUiDHhV3X2x4gvWFPUlKUbTmpEq2kN2-GHx403HKhS-QZn81mhSqlbWvYXDopY0I3LQgqVFcq1BIUuS_mnhIIP2jTALHvQYG1tL3ywgaJpLj7rAjND6hZsteoRvb39x9GlUEoLfvltMZL9_4M77EoSGrFJhYavAm-iA0-psH3Jia0lEymLANrk4idR_tjQintS2nEYOE4WLClwfP22H7b6QeP818MPWnvOcwJ_ldPAwutxMoYVPQ_XjHOKwa8YoT3tP0EUwww-_YHmEey52IV47EKH8dDhEAnBmmKR4mnvScdeNLnMJ8MU4yHKcQ45XiGgy4e8Qbdby1LtyNbby04VdhgwTP3qnBFBuqCR6EUdsSVtmFqwWtc0DcoS6mWXk_TebQv3YL5CK1Xk_ODuDSy_CIV5gRm2DiwuL5PKJdVd9DFUV9oRbn82aElc6_uogHxuzwP0DGBvbvCtcs17tO-6vZyy_yI2QIaWW8ydva1RcVyUPbsdahYNz1L5u2a7VjsSVnst5yRG-a6--sjU1rhqSNTVM1EJetykqqXyfSRueCF2rmwYUU63yjBMzIrjPiq9XfNewlLAw3PFlBbp2IpSZvLcHN1F1jEW1DXWu89u3-YPX1X\n\n---\ndisplayMode: compact\n---\n\ngantt\n dateFormat X\n axisFormat %s\n tickInterval 1\n title ↓ threads | time →\n\n section (same_thread, same_thread)\n A.test1() :ass1, 0, 1\n A.test2() :ass2, after ass1, 2\n B.test1() :bss1, after ass2, 3\n B.test2() :bss2, after bss1, 4\n\n section (same_thread, concurrent)\n A.test1() :asc1, 0, 1\n A.test2() :asc2, after asc1, 2\n B.test1() :bsc1, 0, 1\n B.test2() :bsc2, after bsc1, 2\n\n section (concurrent, same_thread)\n A.test1() :acs1, 0, 1\n A.test2() :acs2, 0, 1\n B.test1() :bcs1, after acs1, 2\n B.test2() :bcs2, after acs2, 2\n\n section (concurrent, concurrent)\n A.test1() :acc1, 0, 1\n A.test2() :acc2, 0, 1\n B.test1() :bcc1, 0, 1\n B.test2() :bcc2, 0, 1\n\n////\nimage::writing-tests_execution_mode.svg[caption='',title='Default execution mode configuration combinations']\n\nIf the `junit.jupiter.execution.parallel.mode.classes.default` configuration parameter is\nnot explicitly set, the value for `junit.jupiter.execution.parallel.mode.default` will be\nused instead.\n\n[[config]]\n== Configuration\n\n[[config-executor-service]]\n=== Executor Service\n\nIf parallel execution is enabled, a thread pool is used behind the scenes to execute tests\nconcurrently. You can configure which implementation of `HierarchicalTestExecutorService`\nis used be setting the `junit.jupiter.execution.parallel.config.executor-service`\nconfiguration parameter to one of the following options:\n\n`fork_join_pool` (default)::\nUse an executor service that is backed by a `ForkJoinPool` from the JDK. This will cause\ntests to be executed in a `ForkJoinWorkerThread`. In some cases, usages of\n`ForkJoinPool` in test or production code or calls to blocking JDK APIs may cause the\nnumber of concurrently executing tests to increase. To avoid this situation, please use\n`worker_thread_pool`.\n\n`worker_thread_pool` (experimental)::\nUse an executor service that is backed by a regular thread pool and does not create\nadditional threads if test or production code uses `ForkJoinPool` or calls a blocking\nAPI in the JDK.\n\nWARNING: Using `worker_thread_pool` is currently an _experimental_ feature. You're invited\nto give it a try and provide feedback to the JUnit team so they can improve and eventually\nxref:api-evolution.adoc[promote] this feature.\n\n[[config-strategies]]\n=== Strategies\n\nProperties such as the desired parallelism and the maximum pool size can be configured\nusing a `{ParallelExecutionConfigurationStrategy}`. The JUnit Platform provides two\nimplementations out of the box: `dynamic` and `fixed`. Alternatively, you may implement a\n`custom` strategy.\n\nTo select a strategy, set the `junit.jupiter.execution.parallel.config.strategy`\nconfiguration parameter to one of the following options.\n\n`dynamic`::\n Computes the desired parallelism based on the number of available processors/cores\n multiplied by the `junit.jupiter.execution.parallel.config.dynamic.factor`\n configuration parameter (defaults to `1`).\n The optional `junit.jupiter.execution.parallel.config.dynamic.max-pool-size-factor`\n configuration parameter can be used to limit the maximum number of threads.\n\n`fixed`::\n Uses the mandatory `junit.jupiter.execution.parallel.config.fixed.parallelism`\n configuration parameter as the desired parallelism.\n The optional `junit.jupiter.execution.parallel.config.fixed.max-pool-size`\n configuration parameter can be used to limit the maximum number of threads.\n\n`custom`::\n Allows you to specify a custom `{ParallelExecutionConfigurationStrategy}`\n implementation via the mandatory `junit.jupiter.execution.parallel.config.custom.class`\n configuration parameter to determine the desired configuration.\n\nIf no configuration strategy is set, JUnit Jupiter uses the `dynamic` configuration\nstrategy with a factor of `1`. Consequently, the desired parallelism will be equal to the\nnumber of available processors/cores.\n\n.Parallelism alone does not imply maximum number of concurrent threads\nNOTE: By default, JUnit Jupiter does not guarantee that the number of threads used to\nexecute test will not exceed the configured parallelism. For example, when using one\nof the synchronization mechanisms described in the next section, the executor service\nimplementation may spawn additional threads to ensure execution continues with sufficient\nparallelism. If you require such guarantees, it is possible to limit the maximum number of\nthreads by configuring the maximum pool size of the `dynamic`, `fixed` and `custom`\nstrategies.\n\n[[config-properties]]\n=== Relevant properties\n\nThe following table lists relevant properties for configuring parallel execution. See\nxref:running-tests/configuration-parameters.adoc[] for details on how to set such properties.\n\n==== General\n\n`junit.jupiter.execution.parallel.enabled=true|false`::\n Enable/disable parallel test execution (defaults to `false`).\n\n`junit.jupiter.execution.parallel.mode.default=concurrent|same_thread`::\n Default execution mode of nodes in the test tree (defaults to `same_thread`).\n\n`junit.jupiter.execution.parallel.mode.classes.default=concurrent|same_thread`::\n Default execution mode of top-level classes (defaults to `same_thread`).\n\n`junit.jupiter.execution.parallel.config.executor-service=fork_join_pool|worker_thread_pool`::\n Type of `HierarchicalTestExecutorService` to use for parallel execution (defaults to\n `fork_join_pool`).\n\n`junit.jupiter.execution.parallel.config.strategy=dynamic|fixed|custom`::\n Execution strategy for desired parallelism, maximum pool size, etc. (defaults to `dynamic`).\n\n==== Dynamic strategy\n\n`junit.jupiter.execution.parallel.config.dynamic.factor=decimal`::\n Factor to be multiplied by the number of available processors/cores to determine the\n desired parallelism for the ```dynamic``` configuration strategy.\n Must be a positive decimal number (defaults to `1.0`).\n\n`junit.jupiter.execution.parallel.config.dynamic.max-pool-size-factor=decimal`::\n Factor to be multiplied by the number of available processors/cores and the value of\n `junit.jupiter.execution.parallel.config.dynamic.factor` to determine the desired\n parallelism for the ```dynamic``` configuration strategy.\n Must be a positive decimal number greater than or equal to `1.0` (defaults to 256 plus\n the value of `junit.jupiter.execution.parallel.config.dynamic.factor` multiplied by the\n number of available processors/cores)\n\n`junit.jupiter.execution.parallel.config.dynamic.saturate=true|false`::\n Enable/disable saturation of the underlying `ForkJoinPool` for the ```dynamic```\n configuration strategy (defaults to `true`). Only used if\n `junit.jupiter.execution.parallel.config.executor-service` is set to `fork_join_pool`.\n\n==== Fixed strategy\n\n`junit.jupiter.execution.parallel.config.fixed.parallelism=integer`::\n Desired parallelism for the ```fixed``` configuration strategy (no default value). Must\n be a positive integer.\n\n`junit.jupiter.execution.parallel.config.fixed.max-pool-size=integer`::\n Desired maximum pool size of the underlying fork-join pool for the ```fixed```\n configuration strategy. Must be a positive integer greater than or equal to\n `junit.jupiter.execution.parallel.config.fixed.parallelism` (defaults to 256 plus the\n value of `junit.jupiter.execution.parallel.config.fixed.parallelism`).\n\n`junit.jupiter.execution.parallel.config.fixed.saturate=true|false`::\n Enable/disable saturation of the underlying `ForkJoinPool` for the ```fixed```\n configuration strategy (defaults to `true`). Only used if\n `junit.jupiter.execution.parallel.config.executor-service` is set to `fork_join_pool`.\n\n==== Custom strategy\n\n`junit.jupiter.execution.parallel.config.custom.class=classname`::\n Fully qualified class name of the `ParallelExecutionConfigurationStrategy` to be used\n for the ```custom``` configuration strategy (no default value).\n\n[[synchronization]]\n== Synchronization\n\nIn addition to controlling the execution mode using the `{Execution}` annotation, JUnit\nJupiter provides another annotation-based declarative synchronization mechanism. The\n`{ResourceLock}` annotation allows you to declare that a test class or method uses a\nspecific shared resource that requires synchronized access to ensure reliable test\nexecution. The shared resource is identified by a unique name which is a `String`. The\nname can be user-defined or one of the predefined constants in `{Resources}`:\n`SYSTEM_PROPERTIES`, `SYSTEM_OUT`, `SYSTEM_ERR`, `LOCALE`, or `TIME_ZONE`.\n\nIn addition to declaring these shared resources statically, the `{ResourceLock}`\nannotation has a `providers` attribute that allows registering implementations of the\n`{ResourceLocksProvider}` interface that can add shared resources dynamically at runtime.\nNote that resources declared statically with `{ResourceLock}` annotation are combined with\nresources added dynamically by `{ResourceLocksProvider}` implementations.\n\nIf the tests in the following example were run in parallel _without_ the use of\n`{ResourceLock}`, they would be _flaky_. Sometimes they would pass, and at other times they\nwould fail due to the inherent race condition of writing and then reading the same JVM\nSystem Property.\n\nWhen access to shared resources is declared using the `{ResourceLock}` annotation, the\nJUnit Jupiter engine uses this information to ensure that no conflicting tests are run in\nparallel. This guarantee extends to lifecycle methods of a test class or method. For\nexample, if a test method is annotated with a `{ResourceLock}` annotation, the \"lock\" will\nbe acquired before any `@BeforeEach` methods are executed and released after all\n`@AfterEach` methods have been executed.\n\n[NOTE]\n.Running tests in isolation\n====\nIf most of your test classes can be run in parallel without any synchronization but you\nhave some test classes that need to run in isolation, you can mark the latter with the\n`{Isolated}` annotation. Tests in such classes are executed sequentially without any other\ntests running at the same time.\n====\n\nIn addition to the `String` that uniquely identifies the shared resource, you may specify\nan access mode. Two tests that require `READ` access to a shared resource may run in\nparallel with each other but not while any other test that requires `READ_WRITE` access\nto the same shared resource is running.\n\n[source,java]\n.Declaring shared resources \"statically\" with `{ResourceLock}` annotation\n----\ninclude::example$java/example/sharedresources/StaticSharedResourcesDemo.java[tags=user_guide]\n----\n\n[source,java]\n.Adding shared resources \"dynamically\" with `{ResourceLocksProvider}` implementation\n----\ninclude::example$java/example/sharedresources/DynamicSharedResourcesDemo.java[tags=user_guide]\n----\n\nAlso, \"static\" shared resources can be declared for _direct_ child nodes via the `target`\nattribute in the `{ResourceLock}` annotation, the attribute accepts a value from\nthe `{ResourceLockTarget}` enum.\n\nSpecifying `target = CHILDREN` in a class-level `{ResourceLock}` annotation\nhas the same semantics as adding an annotation with the same `value` and `mode`\nto each test method and nested test class declared in this class.\n\nThis may improve parallelization when a test class declares a `READ` lock,\nbut only a few methods hold a `READ_WRITE` lock.\n\nTests in the following example would run in the `SAME_THREAD` if the `{ResourceLock}`\ndidn't have `target = CHILDREN`. This is because the test class declares a `READ`\nshared resource, but one test method holds a `READ_WRITE` lock,\nwhich would force the `SAME_THREAD` execution mode for all the test methods.\n\n[source,java]\n.Declaring shared resources for child nodes with `target` attribute\n----\ninclude::example$java/example/sharedresources/ChildrenSharedResourcesDemo.java[tags=user_guide]\n----\n"
},
{
"path": "documentation/modules/ROOT/pages/writing-tests/parameterized-classes-and-tests.adoc",
"content": "= Parameterized Classes and Tests\n\n_Parameterized tests_ make it possible to run a test method multiple times with different\narguments. They are declared just like regular `@Test` methods but use the\n`{ParameterizedTest}` annotation instead.\n\n_Parameterized classes_ make it possible to run _all_ tests in a test class, including\nxref:writing-tests/nested-tests.adoc[], multiple times with different arguments. They are declared just\nlike regular test classes and may contain any supported test method type (including\n`@ParameterizedTest`) but annotated with the `{ParameterizedClass}` annotation.\n\nWARNING: _Parameterized classes_ are currently an _experimental_ feature. You're invited\nto give it a try and provide feedback to the JUnit team so they can improve and eventually\nxref:api-evolution.adoc[promote] this feature.\n\nRegardless of whether you are parameterizing a test method or a test class, you must\ndeclare at least one <> that will\nprovide the arguments for each invocation and then\n<> the arguments in the\nparameterized method or class, respectively.\n\nThe following example demonstrates a parameterized test that uses the `@ValueSource`\nannotation to specify a `String` array as the source of arguments.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=first_example]\n----\n\nWhen executing the above parameterized test method, each invocation will be reported\nseparately. For instance, the `ConsoleLauncher` will print output similar to the\nfollowing.\n\n....\npalindromes(String) ✔\n├─ [1] candidate = \"racecar\" ✔\n├─ [2] candidate = \"radar\" ✔\n└─ [3] candidate = \"able was I ere I saw elba\" ✔\n....\n\nThe same `@ValueSource` annotation can be used to specify the source of arguments for a\n`@ParameterizedClass`.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedClassDemo.java[tags=first_example]\n----\n\nWhen executing the above parameterized test class, each invocation will be reported\nseparately. For instance, the `ConsoleLauncher` will print output similar to the\nfollowing.\n\n....\nPalindromeTests ✔\n├─ [1] candidate = \"racecar\" ✔\n│ ├─ palindrome() ✔\n│ └─ reversePalindrome() ✔\n├─ [2] candidate = \"radar\" ✔\n│ ├─ palindrome() ✔\n│ └─ reversePalindrome() ✔\n└─ [3] candidate = \"able was I ere I saw elba\" ✔\n ├─ palindrome() ✔\n └─ reversePalindrome() ✔\n....\n\n[[setup]]\n== Required Setup\n\nIn order to use parameterized classes or tests you need to add a dependency on the\n`junit-jupiter-params` artifact. Please refer to xref:appendix.adoc#dependency-metadata[Dependency Metadata] for details.\n\n[[consuming-arguments]]\n== Consuming Arguments\n\n[[consuming-arguments-methods]]\n=== Parameterized Tests\n\nParameterized test methods _consume_ arguments directly from the configured source (see\n<>) following a one-to-one correlation between argument source index and method\nparameter index (see examples in <>). However, a parameterized test\nmethod may also choose to _aggregate_ arguments from the source into a single object\npassed to the method (see <>). Additional arguments may also be\nprovided by a `ParameterResolver` — for example, to obtain an instance of `TestInfo`,\n`TestReporter`, and so forth. Specifically, a parameterized test method must declare\nformal parameters according to the following rules.\n\n* Zero or more _indexed parameters_ must be declared first.\n* Zero or more _aggregators_ must be declared next.\n* Zero or more arguments supplied by a `ParameterResolver` must be declared last.\n\nIn this context, an _indexed parameter_ is an argument for a given index in the\n`{Arguments}` provided by an `{ArgumentsProvider}` that is passed as an argument to the\nparameterized method at the same index in the method's formal parameter list. An\n_aggregator_ is any parameter of type `{ArgumentsAccessor}` or any parameter annotated\nwith `{AggregateWith}`.\n\n[[consuming-arguments-classes]]\n=== Parameterized Classes\n\nParameterized classes _consume_ arguments directly from the configured source (see\n<>); either via their unique constructor or via\nfield injection. If a `{Parameter}`-annotated field is declared in the parameterized class\nor one of its superclasses, field injection will be used. Otherwise, constructor injection\nwill be used.\n\n[[consuming-arguments-constructor-injection]]\n==== Constructor Injection\n\nWARNING: Constructor injection can only be used with the (default) `PER_METHOD`\nxref:writing-tests/test-instance-lifecycle.adoc[test instance lifecycle] mode. Please use\n<>\nwith the `PER_CLASS` mode instead.\n\nFor constructor injection, the same rules apply as defined for\n<>\nabove. In the following example, two arguments are injected into the constructor of the\ntest class.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedClassDemo.java[tags=constructor_injection]\n----\n\nYou may use _records_ to implement parameterized classes that avoid the boilerplate code\nof declaring a test class constructor.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedRecordDemo.java[tags=example]\n----\n\n[[consuming-arguments-field-injection]]\n==== Field Injection\n\nFor field injection, the following rules apply for fields annotated with `@Parameter`.\n\n* Zero or more _indexed parameters_ may be declared; each must have a unique index\n specified in its `@Parameter(index)` annotation. The index may be omitted if there is\n only one indexed parameter. If there are at least two indexed parameter declarations,\n there must be declarations for all indexes from 0 to the largest declared index.\n* Zero or more _aggregators_ may be declared; each without specifying an index in its\n `@Parameter` annotation.\n* Zero or more other fields may be declared as usual as long as they're not annotated with\n `@Parameter`.\n\nIn this context, an _indexed parameter_ is an argument for a given index in the\n`{Arguments}` provided by an `{ArgumentsProvider}` that is injected into a field annotated\nwith `@Parameter(index)`. An _aggregator_ is any `@Parameter`-annotated field of type\n{ArgumentsAccessor} or any field annotated with {AggregateWith}.\n\nThe following example demonstrates how to use field injection to consume multiple\narguments in a parameterized class.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedClassDemo.java[tags=field_injection]\n----\n\nIf field injection is used, no constructor parameters will be resolved with arguments from\nthe source. Other xref:writing-tests/dependency-injection-for-constructors-and-methods.adoc[`ParameterResolver` extensions]\nmay resolve constructor parameters as usual, though.\n\n[[consuming-arguments-lifecycle-method]]\n==== Lifecycle Methods\n\n`{BeforeParameterizedClassInvocation}` and `{AfterParameterizedClassInvocation}` can also\nbe used to consume arguments if their `injectArguments` attribute is set to `true` (the\ndefault). If so, their method signatures must follow the same rules apply as defined for\n<> and\nadditionally use the same parameter types as the _indexed parameters_ of the parameterized\ntest class. Please refer to the Javadoc of `{BeforeParameterizedClassInvocation}` and\n`{AfterParameterizedClassInvocation}` for details and to the\n<> section for an\nexample.\n\n[NOTE]\n.AutoCloseable arguments\n====\nArguments that implement `java.lang.AutoCloseable` (or `java.io.Closeable` which extends\n`java.lang.AutoCloseable`) will be automatically closed after the parameterized class or\ntest invocation.\n\nTo prevent this from happening, set the `autoCloseArguments` attribute in\n`@ParameterizedTest` to `false`. Specifically, if an argument that implements\n`AutoCloseable` is reused for multiple invocations of the same parameterized class or test\nmethod, you must specify the `autoCloseArguments = false` on the `{ParameterizedClass}` or\n`{ParameterizedTest}` annotation to ensure that the argument is not closed between\ninvocations.\n====\n\n[[consuming-arguments-other-extensions]]\n=== Other Extensions\n\nOther extensions can access the parameters and resolved arguments of a parameterized test\nor class by retrieving a `{ParameterInfo}` object from the `{ExtensionContext_Store}`.\nPlease refer to the Javadoc of `{ParameterInfo}` for details.\n\n[[sources]]\n== Sources of Arguments\n\nOut of the box, JUnit Jupiter provides quite a few _source_ annotations. Each of the\nfollowing subsections provides a brief overview and an example for each of them. Please\nrefer to the Javadoc in the `{params-provider-package}` package for additional\ninformation.\n\nTIP: All source annotations in this section are applicable to both `{ParameterizedClass}`\nand `{ParameterizedTest}`. For the sake of brevity, the examples in this section will only\nshow how to use them with `{ParameterizedTest}` methods.\n\n[[sources-ValueSource]]\n=== @ValueSource\n\n`@ValueSource` is one of the simplest possible sources. It lets you specify a single\narray of literal values and can only be used for providing a single argument per\nparameterized test invocation.\n\nThe following types of literal values are supported by `@ValueSource`.\n\n- `short`\n- `byte`\n- `int`\n- `long`\n- `float`\n- `double`\n- `char`\n- `boolean`\n- `java.lang.String`\n- `java.lang.Class`\n\nFor example, the following `@ParameterizedTest` method will be invoked three times, with\nthe values `1`, `2`, and `3` respectively.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=ValueSource_example]\n----\n\n[[sources-null-and-empty]]\n=== Null and Empty Sources\n\nIn order to check corner cases and verify proper behavior of our software when it is\nsupplied _bad input_, it can be useful to have `null` and _empty_ values supplied to our\nparameterized tests. The following annotations serve as sources of `null` and empty values\nfor parameterized tests that accept a single argument.\n\n* `{NullSource}`: provides a single `null` argument to the annotated `@ParameterizedClass`\n or `@ParameterizedTest`.\n - `@NullSource` cannot be used for a parameter that has a primitive type.\n* `{EmptySource}`: provides a single _empty_ argument to the annotated\n `@ParameterizedClass` or `@ParameterizedTest` for parameters of the following types:\n `java.lang.String`, `java.lang.Iterable`, `java.util.Iterator`, `java.util.ListIterator`\n `java.util.Collection` (and concrete subtypes with a `public` no-arg constructor),\n `java.util.List`, `java.util.Set`, `java.util.SortedSet`, `java.util.NavigableSet`,\n `java.util.Map` (and concrete subtypes with a `public` no-arg constructor),\n `java.util.SortedMap`, `java.util.NavigableMap`, primitive arrays (for example, `int[]`,\n `char[][]`, etc.), object arrays (for example, `String[]`, `Integer[][]`, etc.).\n* `{NullAndEmptySource}`: a _composed annotation_ that combines the functionality of\n `@NullSource` and `@EmptySource`.\n\nIf you need to supply multiple varying types of _blank_ strings to a parameterized\nclass or test, you can achieve that using\n<> -- for example,\n`@ValueSource(strings = {\"{nbsp}\", \"{nbsp}{nbsp}{nbsp}\", \"\\t\", \"\\n\"})`.\n\nYou can also combine `@NullSource`, `@EmptySource`, and `@ValueSource` to test a wider\nrange of `null`, _empty_, and _blank_ input. The following example demonstrates how to\nachieve this for strings.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=NullAndEmptySource_example1]\n----\n\nMaking use of the composed `@NullAndEmptySource` annotation simplifies the above as\nfollows.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=NullAndEmptySource_example2]\n----\n\nNOTE: Both variants of the `nullEmptyAndBlankStrings(String)` parameterized test method\nresult in six invocations: 1 for `null`, 1 for the empty string, and 4 for the explicit\nblank strings supplied via `@ValueSource`.\n\n[[sources-EnumSource]]\n=== @EnumSource\n\n`@EnumSource` provides a convenient way to use `Enum` constants.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=EnumSource_example]\n----\n\nThe annotation's `value` attribute is optional. When omitted, the declared type of the\nfirst parameter is used. The test will fail if it does not reference an enum type.\nThus, the `value` attribute is required in the above example because the method parameter\nis declared as `TemporalUnit`, i.e. the interface implemented by `ChronoUnit`, which isn't\nan enum type. Changing the method parameter type to `ChronoUnit` allows you to omit the\nexplicit enum type from the annotation as follows.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=EnumSource_example_autodetection]\n----\n\nThe annotation provides an optional `names` attribute that lets you specify which\nconstants shall be used, like in the following example.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=EnumSource_include_example]\n----\n\nIn addition to `names`, you can use the `from` and `to` attributes to specify a range of\nconstants. The range starts from the constant specified in the `from` attribute and\nincludes all subsequent constants up to and including the one specified in the `to`\nattribute, based on the natural order of the enum constants.\n\nIf `from` and `to` attributes are omitted, they default to the first and last constants\nin the enum type, respectively. If all `names`, `from`, and `to` attributes are omitted,\nall constants will be used. The following example demonstrates how to specify a range of\nconstants.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=EnumSource_range_example]\n----\n\nThe `@EnumSource` annotation also provides an optional `mode` attribute that enables\nfine-grained control over which constants are passed to the test method. For example, you\ncan exclude names from the enum constant pool or specify regular expressions as in the\nfollowing examples.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=EnumSource_exclude_example]\n----\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=EnumSource_regex_example]\n----\n\nYou can also combine `mode` with the `from`, `to` and `names` attributes to define a\nrange of constants while excluding specific values from that range as shown below.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=EnumSource_range_exclude_example]\n----\n\n[[sources-MethodSource]]\n=== @MethodSource\n\n`{MethodSource}` allows you to refer to one or more _factory_ methods of the test class\nor external classes.\n\nFactory methods within the test class must be `static` unless the test class is annotated\nwith `@TestInstance(Lifecycle.PER_CLASS)`; whereas, factory methods in external classes\nmust always be `static`.\n\nEach factory method must generate a _stream_ of _arguments_, and each set of arguments\nwithin the stream will be provided as the physical arguments for individual invocations of\nthe annotated `@ParameterizedClass` or `@ParameterizedTest`. Generally speaking this\ntranslates to a `Stream` of `Arguments` (i.e., `Stream`); however, the actual\nconcrete return type can take on many forms. In this context, a \"stream\" is anything that\nJUnit can reliably convert into a `Stream`, such as `Stream`, `DoubleStream`,\n`LongStream`, `IntStream`, `Collection`, `Iterator`, `Iterable`, an array of objects or\nprimitives, or any type that provides an `iterator(): Iterator` method (such as, for\nexample, a `kotlin.sequences.Sequence`). The \"arguments\" within the stream can be supplied\nas an instance of `Arguments`, an array of objects (for example, `Object[]`), or a single\nvalue if the parameterized class or test method accepts a single argument.\n\nIf the return type is `Stream` or one of the primitive streams,\nJUnit will properly close it by calling `BaseStream.close()`,\nmaking it safe to use a resource such as `Files.lines()`.\n\nIf you only need a single parameter, you can return a `Stream` of instances of the\nparameter type as demonstrated in the following example.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=simple_MethodSource_example]\n----\n\nFor a `@ParameterizedClass`, providing a factory method name via `@MethodSource` is\nmandatory. For a `@ParameterizedTest`, if you do not explicitly provide a factory method\nname, JUnit Jupiter will search for a _factory_ method with the same name as the current\n`@ParameterizedTest` method by convention. This is demonstrated in the following example.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=simple_MethodSource_without_value_example]\n----\n\nStreams for primitive types (`DoubleStream`, `IntStream`, and `LongStream`) are also\nsupported as demonstrated by the following example.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=primitive_MethodSource_example]\n----\n\nIf a parameterized class or test method declares multiple parameters, you need to return a\ncollection, stream, or array of `Arguments` instances or object arrays as shown below (see\nthe Javadoc for `{MethodSource}` for further details on supported return types). Note that\n`arguments(Object...)` is a static factory method defined in the `Arguments` interface. In\naddition, `Arguments.of(Object...)` may be used as an alternative to\n`arguments(Object...)`.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=multi_arg_MethodSource_example]\n----\n\nAn external, `static` _factory_ method can be referenced by providing its _fully qualified\nmethod name_ as demonstrated in the following example.\n\n[source,java,indent=0]\n----\npackage example;\n\ninclude::example$java/example/ExternalMethodSourceDemo.java[tags=external_MethodSource_example]\n----\n\nFactory methods can declare parameters, which will be provided by registered\nimplementations of the `ParameterResolver` extension API. In the following example, the\nfactory method is referenced by its name since there is only one such method in the test\nclass. If there are several local methods with the same name, parameters can also be\nprovided to differentiate them – for example, `@MethodSource(\"factoryMethod()\")` or\n`@MethodSource(\"factoryMethod(java.lang.String)\")`. Alternatively, the factory method\ncan be referenced by its fully qualified method name — for example,\n`@MethodSource(\"example.MyTests#factoryMethod(java.lang.String)\")`.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/MethodSourceParameterResolutionDemo.java[tags=parameter_resolution_MethodSource_example]\n----\n\n[[sources-FieldSource]]\n=== @FieldSource\n\n`{FieldSource}` allows you to refer to one or more fields of the test class or external\nclasses.\n\nFields within the test class must be `static` unless the test class is annotated with\n`@TestInstance(Lifecycle.PER_CLASS)`; whereas, fields in external classes must always be\n`static`.\n\nEach field must be able to supply a _stream_ of arguments, and each set of \"arguments\"\nwithin the \"stream\" will be provided as the physical arguments for individual invocations\nof the annotated `@ParameterizedClass` or `@ParameterizedTest`.\n\nIn this context, a \"stream\" is anything that JUnit can reliably convert to a `Stream`;\nhowever, the actual concrete field type can take on many forms. Generally speaking this\ntranslates to a `Collection`, an `Iterable`, a `Supplier` of a stream (`Stream`,\n`DoubleStream`, `LongStream`, or `IntStream`), a `Supplier` of an `Iterator`, an array of\nobjects or primitives, or any type that provides an `iterator(): Iterator` method (such\nas, for example, a `kotlin.sequences.Sequence`). Each set of \"arguments\" within the\n\"stream\" can be supplied as an instance of `Arguments`, an array of objects (for example,\n`Object[]`, `String[]`, etc.), or a single value if the parameterized class or test method accepts\na single argument.\n\n[WARNING]\n====\nIn contrast to the supported return types for\n<> factory\nmethods, the value of a `@FieldSource` field cannot be an instance of `Stream`,\n`DoubleStream`, `LongStream`, `IntStream`, or `Iterator`, since the values of such types\nare _consumed_ the first time they are processed. However, if you wish to use one of\nthese types, you can wrap it in a `Supplier` — for example, `Supplier`.\n====\n\nIf the `Supplier` return type is `Stream` or one of the primitive streams,\nJUnit will properly close it by calling `BaseStream.close()`,\nmaking it safe to use a resource such as `Files.lines()`.\n\nPlease note that a one-dimensional array of objects supplied as a set of \"arguments\" will\nbe handled differently than other types of arguments. Specifically, all the elements of a\none-dimensional array of objects will be passed as individual physical arguments to the\n`@ParameterizedClass` or `@ParameterizedTest`. See the Javadoc for `{FieldSource}` for\nfurther details.\n\nFor a `@ParameterizedClass`, providing a field name via `@FieldSource` is mandatory. For a\n`@ParameterizedTest`, if you do not explicitly provide a field name, JUnit Jupiter will\nsearch in the test class for a field that has the same name as the current\n`@ParameterizedTest` method by convention. This is demonstrated in the following example.\nThis parameterized test method will be invoked twice: with the values `\"apple\"` and\n`\"banana\"`.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=default_field_FieldSource_example]\n----\n\nThe following example demonstrates how to provide a single explicit field name via\n`@FieldSource`. This parameterized test method will be invoked twice: with the values\n`\"apple\"` and `\"banana\"`.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=explicit_field_FieldSource_example]\n----\n\nThe following example demonstrates how to provide multiple explicit field names via\n`@FieldSource`. This example uses the `listOfFruits` field from the previous example as\nwell as the `additionalFruits` field. Consequently, this parameterized test method will\nbe invoked four times: with the values `\"apple\"`, `\"banana\"`, `\"cherry\"`, and\n`\"dewberry\"`.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=multiple_fields_FieldSource_example]\n----\n\nIt is also possible to provide a `Stream`, `DoubleStream`, `IntStream`, `LongStream`, or\n`Iterator` as the source of arguments via a `@FieldSource` field as long as the stream or\niterator is wrapped in a `java.util.function.Supplier`. The following example demonstrates\nhow to provide a `Supplier` of a `Stream` of named arguments. This parameterized test\nmethod will be invoked twice: with the values `\"apple\"` and `\"banana\"` and with display\nnames `\"Apple\"` and `\"Banana\"`, respectively.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=named_arguments_FieldSource_example]\n----\n\n[NOTE]\n====\nNote that `arguments(Object...)` is a static factory method defined in the\n`org.junit.jupiter.params.provider.Arguments` interface.\n\nSimilarly, `named(String, Object)` is a static factory method defined in the\n`org.junit.jupiter.api.Named` interface.\n====\n\nIf a parameterized class or test method declares multiple parameters, the corresponding\n`@FieldSource` field must be able to provide a collection, stream supplier, or array of\n`Arguments` instances or object arrays as shown below (see the Javadoc for `{FieldSource}`\nfor further details on supported types).\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=multi_arg_FieldSource_example]\n----\n\n[NOTE]\n====\nNote that `arguments(Object...)` is a static factory method defined in the\n`org.junit.jupiter.params.provider.Arguments` interface.\n====\n\nAn external, `static` `@FieldSource` field can be referenced by providing its\n_fully qualified field name_ as demonstrated in the following example.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ExternalFieldSourceDemo.java[tags=external_field_FieldSource_example]\n----\n\n[[sources-CsvSource]]\n=== @CsvSource\n\n`@CsvSource` allows you to express argument lists as comma-separated values (i.e., CSV\n`String` literals). Each string provided via the `value` attribute in `@CsvSource`\nrepresents a CSV record and results in one invocation of the parameterized class or\ntest. The first record may optionally be used to supply CSV headers (see the Javadoc for\nthe `useHeadersInDisplayName` attribute for details and an example).\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=CsvSource_example]\n----\n\nThe default delimiter is a comma (`,`), but you can use another character by setting the\n`delimiter` attribute. Alternatively, the `delimiterString` attribute allows you to use a\n`String` delimiter instead of a single character. However, both delimiter attributes\ncannot be set simultaneously.\n\nBy default, `@CsvSource` uses a single quote (`'`) as its quote character, but this can be\nchanged via the `quoteCharacter` attribute. See the `'lemon, lime'` value in the example\nabove and in the table below. An empty, quoted value (`''`) results in an empty `String`\nunless the `emptyValue` attribute is set; whereas, an entirely _empty_ value is\ninterpreted as a `null` reference. By specifying one or more `nullValues`, a custom value\ncan be interpreted as a `null` reference (see the `NIL` example in the table below). An\n`ArgumentConversionException` is thrown if the target type of a `null` reference is a\nprimitive type.\n\nNOTE: An _unquoted_ empty value will always be converted to a `null` reference regardless\nof any custom values configured via the `nullValues` attribute.\n\nExcept within a quoted string, leading and trailing whitespace in a CSV column is trimmed\nby default. This behavior can be changed by setting the\n`ignoreLeadingAndTrailingWhitespace` attribute to `true`.\n\n[cols=\"50,50\"]\n|===\n| Example Input | Resulting Argument List\n\n| `@CsvSource({ \"apple, banana\" })` | `\"apple\"`, `\"banana\"`\n| `@CsvSource({ \"apple, 'lemon, lime'\" })` | `\"apple\"`, `\"lemon, lime\"`\n| `@CsvSource({ \"apple, ''\" })` | `\"apple\"`, `\"\"`\n| `@CsvSource({ \"apple, \" })` | `\"apple\"`, `null`\n| `@CsvSource(value = { \"apple, banana, NIL\" }, nullValues = \"NIL\")` | `\"apple\"`, `\"banana\"`, `null`\n| `@CsvSource(value = { \" apple , banana\" }, ignoreLeadingAndTrailingWhitespace = false)` | `\" apple \"`, `\" banana\"`\n|===\n\nIf the programming language you are using supports Java _text blocks_ or equivalent\nmulti-line string literals, you can alternatively use the `textBlock` attribute of\n`@CsvSource`. Each record within a text block represents a CSV record and results in one\ninvocation of the parameterized class or test. The first record may optionally be used to\nsupply CSV headers by setting the `useHeadersInDisplayName` attribute to `true` as in the\nexample below.\n\nUsing a text block, the previous example can be implemented as follows.\n\n[source,java,indent=0]\n----\n@ParameterizedTest\n@CsvSource(useHeadersInDisplayName = true, textBlock = \"\"\"\n\tFRUIT, RANK\n\tapple, 1\n\tbanana, 2\n\t'lemon, lime', 0xF1\n\tstrawberry, 700_000\n\t\"\"\")\nvoid testWithCsvSource(String fruit, int rank) {\n\t// ...\n}\n----\n\nThe generated display names for the previous example include the CSV header names.\n\n----\n[1] FRUIT = \"apple\", RANK = \"1\"\n[2] FRUIT = \"banana\", RANK = \"2\"\n[3] FRUIT = \"lemon, lime\", RANK = \"0xF1\"\n[4] FRUIT = \"strawberry\", RANK = \"700_000\"\n----\n\nIn contrast to CSV records supplied via the `value` attribute, a text block can contain\ncomments. Any line beginning with the value of the `commentCharacter` attribute (`+++#+++`\nby default) will be treated as a comment and ignored. Note that there is one exception\nto this rule: if the comment character appears within a quoted field, it loses\nits special meaning.\n\nThe comment character must be the first character on the line without any leading\nwhitespace. It is therefore recommended that the closing text block delimiter (`\"\"\"`)\nbe placed either at the end of the last line of input or on the following line,\nleft aligned with the rest of the input (as can be seen in the example below which\ndemonstrates formatting similar to a table).\n\n[source,java,indent=0]\n----\n@ParameterizedTest\n@CsvSource(delimiter = '|', quoteCharacter = '\"', textBlock = \"\"\"\n\t#-----------------------------\n\t# FRUIT | RANK\n\t#-----------------------------\n\t apple | 1\n\t#-----------------------------\n\t banana | 2\n\t#-----------------------------\n\t \"lemon lime\" | 0xF1\n\t#-----------------------------\n\t strawberry | 700_000\n\t#-----------------------------\n\t\"\"\")\nvoid testWithCsvSource(String fruit, int rank) {\n\t// ...\n}\n----\n\n[NOTE]\n====\nJava's https://docs.oracle.com/en/java/javase/17/text-blocks/index.html[text block]\nfeature automatically removes _incidental whitespace_ when the code is compiled.\nHowever other JVM languages such as Groovy and Kotlin do not. Thus, if you are using a\nprogramming language other than Java and your text block contains comments or new lines\nwithin quoted strings, you will need to ensure that there is no leading whitespace within\nyour text block.\n====\n\n[[sources-CsvFileSource]]\n=== @CsvFileSource\n\n`@CsvFileSource` lets you use comma-separated value (CSV) files from the classpath or the\nlocal file system. Each record from a CSV file results in one invocation of the\nparameterized class or test. The first record may optionally be used to supply CSV\nheaders. You can instruct JUnit to ignore the headers via the `numLinesToSkip` attribute.\nIf you would like for the headers to be used in the display names, you can set the\n`useHeadersInDisplayName` attribute to `true`. The examples below demonstrate the use of\n`numLinesToSkip` and `useHeadersInDisplayName`.\n\nThe default delimiter is a comma (`,`), but you can use another character by setting the\n`delimiter` attribute. Alternatively, the `delimiterString` attribute allows you to use a\n`String` delimiter instead of a single character. However, both delimiter attributes\ncannot be set simultaneously.\n\n.Comments in CSV files\nNOTE: Any line beginning with the value of the `commentCharacter` attribute (`+++#+++`\nby default) will be interpreted as a comment and will be ignored.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=CsvFileSource_example]\n----\n\n[source,csv,indent=0]\n.two-column.csv\n----\ninclude::example$resources/two-column.csv[]\n----\n\nThe following listing shows the generated display names for the first two parameterized\ntest methods above.\n\n----\n[1] country = \"Sweden\", reference = \"1\"\n[2] country = \"Poland\", reference = \"2\"\n[3] country = \"United States of America\", reference = \"3\"\n[4] country = \"France\", reference = \"700_000\"\n----\n\nThe following listing shows the generated display names for the last parameterized test\nmethod above that uses CSV header names.\n\n----\n[1] COUNTRY = \"Sweden\", REFERENCE = \"1\"\n[2] COUNTRY = \"Poland\", REFERENCE = \"2\"\n[3] COUNTRY = \"United States of America\", REFERENCE = \"3\"\n[4] COUNTRY = \"France\", REFERENCE = \"700_000\"\n----\n\nIn contrast to the default syntax used in `@CsvSource`, `@CsvFileSource` uses a double\nquote (`+++\"+++`) as the quote character by default, but this can be changed via the\n`quoteCharacter` attribute. See the `\"United States of America\"` value in the example\nabove. An empty, quoted value (`+++\"\"+++`) results in an empty `String` unless the\n`emptyValue` attribute is set; whereas, an entirely _empty_ value is interpreted as a\n`null` reference. By specifying one or more `nullValues`, a custom value can be\ninterpreted as a `null` reference. An `ArgumentConversionException` is thrown if the\ntarget type of a `null` reference is a primitive type.\n\nNOTE: An _unquoted_ empty value will always be converted to a `null` reference regardless\nof any custom values configured via the `nullValues` attribute.\n\nExcept within a quoted string, leading and trailing whitespace in a CSV column is trimmed\nby default. This behavior can be changed by setting the\n`ignoreLeadingAndTrailingWhitespace` attribute to `true`.\n\n[[sources-ArgumentsSource]]\n=== @ArgumentsSource\n\n`@ArgumentsSource` can be used to specify a custom, reusable `ArgumentsProvider`. Note\nthat an implementation of `ArgumentsProvider` must be declared as either a top-level\nclass or as a `static` nested class.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=ArgumentsSource_example]\n----\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=ArgumentsProvider_example]\n----\n\nIf you wish to implement a custom `ArgumentsProvider` that also consumes an annotation\n(like built-in providers such as `{ValueArgumentsProvider}` or `{CsvArgumentsProvider}`),\nyou have the possibility to extend the `{AnnotationBasedArgumentsProvider}` class.\n\nMoreover, `ArgumentsProvider` implementations may declare constructor parameters in case\nthey need to be resolved by a registered `ParameterResolver` as demonstrated in the\nfollowing example.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=ArgumentsProviderWithConstructorInjection_example]\n----\n\n[[repeatable-sources]]\n=== Multiple sources using repeatable annotations\n\nRepeatable annotations provide a convenient way to specify multiple sources from\ndifferent providers.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=repeatable_annotations]\n----\n\nFollowing the above parameterized test, a test case will run for each argument:\n\n----\n[1] foo\n[2] bar\n----\n\nThe following annotations are repeatable:\n\n* `@ValueSource`\n* `@EnumSource`\n* `@MethodSource`\n* `@FieldSource`\n* `@CsvSource`\n* `@CsvFileSource`\n* `@ArgumentsSource`\n\n[[argument-count-validation]]\n== Argument Count Validation\n\nBy default, when an arguments source provides more arguments than the test method needs,\nthose additional arguments are ignored and the test executes as usual.\nThis can lead to bugs where arguments are never passed to the parameterized class or\nmethod.\n\nTo prevent this, you can set argument count validation to 'strict'.\nThen, any additional arguments will cause an error instead.\n\nTo change this behavior for all tests, set the\n`junit.jupiter.params.argumentCountValidation`\nxref:running-tests/configuration-parameters.adoc[configuration parameter] to `strict`.\nTo change this behavior for a single parameterized class or test method,\nuse the `argumentCountValidation` attribute of the `@ParameterizedClass` or\n`@ParameterizedTest` annotation:\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=argument_count_validation]\n----\n\n[[argument-conversion]]\n== Argument Conversion\n\n[[argument-conversion-widening]]\n=== Widening Conversion\n\nJUnit Jupiter supports\nhttps://docs.oracle.com/javase/specs/jls/se8/html/jls-5.html#jls-5.1.2[Widening Primitive\nConversion] for arguments supplied to a `@ParameterizedClass` or `@ParameterizedTest`.\nFor example, a parameterized class or test method annotated with\n`@ValueSource(ints = { 1, 2, 3 })` can be declared to accept not only an argument of type\n`int` but also an argument of type `long`, `float`, or `double`.\n\n[[argument-conversion-implicit]]\n=== Implicit Conversion\n\nTo support use cases like `@CsvSource`, JUnit Jupiter provides a number of built-in\nimplicit type converters. The conversion process depends on the declared type of each\nmethod parameter.\n\nFor example, if a `@ParameterizedClass` or `@ParameterizedTest` declares a parameter\nof type `TimeUnit` and the actual type supplied by the declared source is a `String`, the\nstring will be automatically converted into the corresponding `TimeUnit` enum constant.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=implicit_conversion_example]\n----\n\n`String` instances are implicitly converted to the following target types.\n\nNOTE: Decimal, hexadecimal, and octal `String` literals will be converted to their\nintegral types: `byte`, `short`, `int`, `long`, and their boxed counterparts.\n\n[[argument-conversion-implicit-table]]\n[cols=\"10,90\"]\n|===\n| Target Type | Example\n\n| `boolean`/`Boolean` | `\"true\"` -> `true` _(only accepts values 'true' or 'false', case-insensitive)_\n| `byte`/`Byte` | `\"15\"`, `\"0xF\"`, or `\"017\"` -> `(byte) 15`\n| `char`/`Character` | `\"o\"` -> `'o'`\n| `short`/`Short` | `\"15\"`, `\"0xF\"`, or `\"017\"` -> `(short) 15`\n| `int`/`Integer` | `\"15\"`, `\"0xF\"`, or `\"017\"` -> `15`\n| `long`/`Long` | `\"15\"`, `\"0xF\"`, or `\"017\"` -> `15L`\n| `float`/`Float` | `\"1.0\"` -> `1.0f`\n| `double`/`Double` | `\"1.0\"` -> `1.0d`\n| `Enum` subclass | `\"SECONDS\"` -> `TimeUnit.SECONDS`\n| `java.io.File` | `\"/path/to/file\"` -> `new File(\"/path/to/file\")`\n| `java.lang.Class` | `\"java.lang.Integer\"` -> `java.lang.Integer.class` _(use `$` for nested classes: `\"java.lang.Thread$State\"`)_\n| `java.lang.Class` | `\"byte\"` -> `byte.class` _(primitive types are supported)_\n| `java.lang.Class` | `\"char[]\"` -> `char[].class` _(array types are supported)_\n| `java.math.BigDecimal` | `\"123.456e789\"` -> `new BigDecimal(\"123.456e789\")`\n| `java.math.BigInteger` | `\"1234567890123456789\"` -> `new BigInteger(\"1234567890123456789\")`\n| `java.net.URI` | `\"https://junit.org/\"` -> `URI.create(\"https://junit.org/\")`\n| `java.net.URL` | `\"https://junit.org/\"` -> `URI.create(\"https://junit.org/\").toURL()`\n| `java.nio.charset.Charset` | `\"UTF-8\"` -> `Charset.forName(\"UTF-8\")`\n| `java.nio.file.Path` | `\"/path/to/file\"` -> `Path.of(\"/path/to/file\")`\n| `java.time.Duration` | `\"PT3S\"` -> `Duration.ofSeconds(3)`\n| `java.time.Instant` | `\"1970-01-01T00:00:00Z\"` -> `Instant.ofEpochMilli(0)`\n| `java.time.LocalDateTime` | `\"2017-03-14T12:34:56.789\"` -> `LocalDateTime.of(2017, 3, 14, 12, 34, 56, 789_000_000)`\n| `java.time.LocalDate` | `\"2017-03-14\"` -> `LocalDate.of(2017, 3, 14)`\n| `java.time.LocalTime` | `\"12:34:56.789\"` -> `LocalTime.of(12, 34, 56, 789_000_000)`\n| `java.time.MonthDay` | `\"--03-14\"` -> `MonthDay.of(3, 14)`\n| `java.time.OffsetDateTime` | `\"2017-03-14T12:34:56.789Z\"` -> `OffsetDateTime.of(2017, 3, 14, 12, 34, 56, 789_000_000, ZoneOffset.UTC)`\n| `java.time.OffsetTime` | `\"12:34:56.789Z\"` -> `OffsetTime.of(12, 34, 56, 789_000_000, ZoneOffset.UTC)`\n| `java.time.Period` | `\"P2M6D\"` -> `Period.of(0, 2, 6)`\n| `java.time.YearMonth` | `\"2017-03\"` -> `YearMonth.of(2017, 3)`\n| `java.time.Year` | `\"2017\"` -> `Year.of(2017)`\n| `java.time.ZonedDateTime` | `\"2017-03-14T12:34:56.789Z\"` -> `ZonedDateTime.of(2017, 3, 14, 12, 34, 56, 789_000_000, ZoneOffset.UTC)`\n| `java.time.ZoneId` | `\"Europe/Berlin\"` -> `ZoneId.of(\"Europe/Berlin\")`\n| `java.time.ZoneOffset` | `\"+02:30\"` -> `ZoneOffset.ofHoursMinutes(2, 30)`\n| `java.util.Currency` | `\"JPY\"` -> `Currency.getInstance(\"JPY\")`\n| `java.util.Locale` | `\"en-US\"` -> `Locale.forLanguageTag(\"en-US\")`\n| `java.util.UUID` | `\"d043e930-7b3b-48e3-bdbe-5a3ccfb833db\"` -> `UUID.fromString(\"d043e930-7b3b-48e3-bdbe-5a3ccfb833db\")`\n|===\n\n[[argument-conversion-implicit-fallback]]\n==== Fallback String-to-Object Conversion\n\nIn addition to implicit conversion from strings to the target types listed in the above\ntable, JUnit Jupiter also provides a fallback mechanism for automatic conversion from a\n`String` to a given target type if the target type declares a suitable _factory method_\nor _factory constructor_ as defined below.\n\n- __factory method__: a non-private, `static` method declared in the target type that\n accepts either a single `String` argument or a single `CharSequence` argument and\n returns an instance of the target type. The name of the method can be arbitrary and need\n not follow any particular convention.\n- __factory constructor__: a non-private constructor in the target type that accepts a\n either a single `String` argument or a single `CharSequence` argument. Note that the\n target type must be declared as either a top-level class or as a `static` nested class.\n\nIf there are multiple _factory methods_ or _factory constructors_, matching proceeds in the\nfollowing order:\n\n1. A single _factory method_ accepting a `String` argument.\n2. A single _factory constructor_ accepting a `String` argument.\n3. A single _factory method_ accepting a `CharSequence` argument.\n4. A single _factory constructor_ accepting a `CharSequence` argument.\n5. A single _factory method_ accepting a `String` argument once all `@Deprecated` factory\nmethods have been removed from the set of methods being considered.\n6. A single _factory method_ accepting a `CharSequence` argument once all `@Deprecated` factory\nmethods have been removed from the set of methods being considered.\n\nFor example, in the following `@ParameterizedTest` method, the `Book` argument will be\ncreated by invoking the `Book.fromTitle(String)` factory method and passing `\"42 Cats\"`\nas the title of the book.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=implicit_fallback_conversion_example]\n----\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=implicit_fallback_conversion_example_Book]\n----\n\n[[argument-conversion-explicit]]\n=== Explicit Conversion\n\nInstead of relying on implicit argument conversion, you may explicitly specify an\n`{ArgumentConverter}` to use for a certain parameter using the `@ConvertWith` annotation\nlike in the following example. Note that an implementation of `ArgumentConverter` must be\ndeclared as either a top-level class or as a `static` nested class.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=explicit_conversion_example]\n----\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=explicit_conversion_example_ToStringArgumentConverter]\n----\n\nIf the converter is only meant to convert one type to another, you can extend\n`TypedArgumentConverter` to avoid boilerplate type checks.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=explicit_conversion_example_TypedArgumentConverter]\n----\n\nExplicit argument converters are meant to be implemented by test and extension authors.\nThus, `junit-jupiter-params` only provides a single explicit argument converter that may\nalso serve as a reference implementation: `JavaTimeArgumentConverter`. It is used via the\ncomposed annotation `JavaTimeConversionPattern`.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=explicit_java_time_converter]\n----\n\nIf you wish to implement a custom `{ArgumentConverter}` that also consumes an annotation\n(like `JavaTimeArgumentConverter`), you have the possibility to extend the\n`{AnnotationBasedArgumentConverter}` class.\n\n[[argument-aggregation]]\n== Argument Aggregation\n\nBy default, each _argument_ provided to a `@ParameterizedClass` or `@ParameterizedTest`\ncorresponds to a single method parameter. Consequently, argument sources which are\nexpected to supply a large number of arguments can lead to large constructor or method\nsignatures, respectively.\n\nIn such cases, an `{ArgumentsAccessor}` can be used instead of multiple parameters. Using\nthis API, you can access the provided arguments through a single argument passed to your\ntest method. In addition, type conversion is supported as discussed in\n<>.\n\nBesides, you can retrieve the current test invocation index with\n`ArgumentsAccessor.getInvocationIndex()`.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=ArgumentsAccessor_example]\n----\n\n_An instance of `ArgumentsAccessor` is automatically injected into any parameter of type\n`ArgumentsAccessor`._\n\n[[argument-aggregation-custom]]\n=== Custom Aggregators\n\nApart from direct access to the arguments of a `@ParameterizedClass` or\n`@ParameterizedTest` using an `ArgumentsAccessor`, JUnit Jupiter also supports the usage\nof custom, reusable _aggregators_.\n\nTo use a custom aggregator, implement the `{ArgumentsAggregator}` interface and register\nit via the `@AggregateWith` annotation on a compatible parameter of the\n`@ParameterizedClass` or `@ParameterizedTest`. The result of the aggregation will then be\nprovided as an argument for the corresponding parameter when the parameterized test is\ninvoked. Note that an implementation of `ArgumentsAggregator` must be declared as either a\ntop-level class or as a `static` nested class.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=ArgumentsAggregator_example]\n----\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=ArgumentsAggregator_example_PersonAggregator]\n----\n\nIf you find yourself repeatedly declaring `@AggregateWith(MyTypeAggregator.class)` for\nmultiple parameterized classes or methods across your codebase, you may wish to create a\ncustom _composed annotation_ such as `@CsvToMyType` that is meta-annotated with\n`@AggregateWith(MyTypeAggregator.class)`. The following example demonstrates this in\naction with a custom `@CsvToPerson` annotation.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=ArgumentsAggregator_with_custom_annotation_example]\n----\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=ArgumentsAggregator_with_custom_annotation_example_CsvToPerson]\n----\n\n\n[[display-names]]\n== Customizing Display Names\n\nBy default, the display name of a parameterized class or test invocation contains the\ninvocation index and a comma-separated list of the `String` representations of all\narguments for that specific invocation. If parameter names are present in the bytecode,\neach argument will be preceded by its parameter name and an equals sign (unless the\nargument is only available via an `ArgumentsAccessor` or `ArgumentAggregator`) – for\nexample, `firstName = \"Jane\"`.\n\n[TIP]\n====\nTo ensure that parameter names are present in the bytecode, test code must be compiled\nwith the `-parameters` compiler flag for Java or with the `-java-parameters` compiler flag\nfor Kotlin.\n====\n\nHowever, you can customize invocation display names via the `name` attribute of the\n`@ParameterizedClass` or `@ParameterizedTest` annotation as in the following example.\n\n======\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=custom_display_names]\n----\n\nWhen executing the above method using the `ConsoleLauncher` you will see output similar to\nthe following.\n\n....\nDisplay name of container ✔\n├─ 1 ==> the rank of \"apple\" is \"1\" ✔\n├─ 2 ==> the rank of \"banana\" is \"2\" ✔\n└─ 3 ==> the rank of \"lemon, lime\" is \"3\" ✔\n....\n======\n\n[NOTE]\n====\nPlease note that `name` is a `MessageFormat` pattern. Thus, a single quote (`'`) needs to\nbe represented as a doubled single quote (`''`) in order to be displayed.\n====\n\nThe following placeholders are supported within custom display names.\n\n[cols=\"20,80\"]\n|===\n| Placeholder | Description\n\n| `\\{displayName}` | the display name of the method\n| `\\{index}` | the current invocation index (1-based)\n| `\\{arguments}` | the complete, comma-separated arguments list\n| `\\{argumentsWithNames}` | the complete, comma-separated arguments list with parameter names\n| `\\{argumentSetName}` | the name of the argument set\n| `\\{argumentSetNameOrArgumentsWithNames}` | `\\{argumentSetName}` or `\\{argumentsWithNames}`, depending on how the arguments are supplied\n| `\\{0}`, `\\{1}`, ... | an individual argument\n|===\n\nNOTE: When including arguments in display names, their string representations are truncated\nif they exceed the configured maximum length. The limit is configurable via the\n`junit.jupiter.params.displayname.argument.maxlength` configuration parameter and defaults\nto 512 characters.\n\nWhen using `@MethodSource`, `@FieldSource`, or `@ArgumentsSource`, you can provide custom\nnames for individual arguments or custom names for entire sets of arguments.\n\nUse the `{Named}` API to provide a custom name for an individual argument, and the custom\nname will be used if the argument is included in the invocation display name, like in the\nexample below.\n\n======\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=named_arguments]\n----\n\nWhen executing the above method using the `ConsoleLauncher` you will see output similar to\nthe following.\n\n....\nA parameterized test with named arguments ✔\n├─ 1: An important file ✔\n└─ 2: Another file ✔\n....\n======\n\n[NOTE]\n====\nNote that `arguments(Object...)` is a static factory method defined in the\n`org.junit.jupiter.params.provider.Arguments` interface.\n\nSimilarly, `named(String, Object)` is a static factory method defined in the\n`org.junit.jupiter.api.Named` interface.\n====\n\nUse the `ArgumentSet` API to provide a custom name for the entire set of arguments, and\nthe custom name will be used as the display name, like in the example below.\n\n======\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=named_argument_set]\n----\n\nWhen executing the above method using the `ConsoleLauncher` you will see output similar to\nthe following.\n\n....\nA parameterized test with named argument sets ✔\n├─ [1] Important files ✔\n└─ [2] Other files ✔\n....\n======\n\n[NOTE]\n====\nNote that `argumentSet(String, Object...)` is a static factory method defined in the\n`org.junit.jupiter.params.provider.Arguments` interface.\n====\n\n[[display-names-quoted-text]]\n=== Quoted Text-based Arguments\n\nAs of JUnit Jupiter 6.0, text-based arguments in display names for parameterized tests are\nquoted by default. In this context, any `CharSequence` (such as a `String`) or `Character`\nis considered text. A `CharSequence` is wrapped in double quotes (`\"`), and a `Character`\nis wrapped in single quotes (`'`).\n\nSpecial characters will be escaped in the quoted text. For example, carriage returns and\nline feeds will be escaped as `\\\\r` and `\\\\n`, respectively.\n\n[TIP]\n====\nThis feature can be disabled by setting the `quoteTextArguments` attributes in\n`@ParameterizedClass` and `@ParameterizedTest` to `false`.\n====\n\nFor example, given a string argument `\"line 1\\nline 2\"`, the physical representation in\nthe display name will be `\"\\\"line 1\\\\nline 2\\\"\"` which is printed as `\"line 1\\nline 2\"`.\nSimilarly, given a string argument `\"\\t\"`, the physical representation in the display name\nwill be `\"\\\"\\\\t\\\"\"` which is printed as `\"\\t\"` instead of a blank string or invisible tab\ncharacter. The same applies for a character argument `'\\t'`, whose physical representation\nin the display name would be `\"'\\\\t'\"` which is printed as `'\\t'`.\n\nFor a concrete example, if you run the first `nullValuesAndBlankStrings(String text)`\nparameterized test method from the <> section above, the following\ndisplay names are generated.\n\n----\n[1] text = null\n[2] text = \"\"\n[3] text = \" \"\n[4] text = \" \"\n[5] text = \"\\t\"\n[6] text = \"\\n\"\n----\n\nIf you run the first `testWithCsvSource(String fruit, int rank)` parameterized test method\nfrom the <> section above, the following display names are generated.\n\n----\n[1] fruit = \"apple\", rank = \"1\"\n[2] fruit = \"banana\", rank = \"2\"\n[3] fruit = \"lemon, lime\", rank = \"0xF1\"\n[4] fruit = \"strawberry\", rank = \"700_000\"\n----\n\n[NOTE]\n====\nThe original source arguments are quoted when generating a display name, and this occurs\nbefore any implicit or explicit argument conversion is performed.\n\nFor example, if a parameterized test accepts `3.14` as a `float` argument that was\nconverted from `\"3.14\"` as an input string, `\"3.14\"` will be present in the display name\ninstead of `3.14`. You can see the effect of this with the `rank` values in the above\nexample.\n====\n\n[[display-names-default-pattern]]\n=== Default Display Name Pattern\n\nIf you'd like to set a default name pattern for all parameterized classes and tests in\nyour project, you can declare the `junit.jupiter.params.displayname.default` configuration\nparameter in the `junit-platform.properties` file as demonstrated in the following example (see\nxref:running-tests/configuration-parameters.adoc[] for other options).\n\n[source,properties,indent=0]\n----\njunit.jupiter.params.displayname.default = {index}\n----\n\n[[display-names-precedence-rules]]\n=== Precedence Rules\n\nThe display name for a parameterized class or test is determined according to the\nfollowing precedence rules:\n\n1. `name` attribute in `@ParameterizedClass` or `@ParameterizedTest`, if present\n2. value of the `junit.jupiter.params.displayname.default` configuration parameter, if present\n3. `DEFAULT_DISPLAY_NAME` constant defined in\n `org.junit.jupiter.params.ParameterizedInvocationConstants`\n\n[[lifecycle-interop]]\n== Lifecycle and Interoperability\n\n[[lifecycle-interop-methods]]\n=== Parameterized Tests\n\nEach invocation of a parameterized test has the same lifecycle as a regular `@Test`\nmethod. For example, `@BeforeEach` methods will be executed before each invocation.\nSimilar to xref:writing-tests/dynamic-tests.adoc[], invocations will appear one by one in the\ntest tree of an IDE. You may at will mix regular `@Test` methods and `@ParameterizedTest`\nmethods within the same test class.\n\nYou may use `ParameterResolver` extensions with `@ParameterizedTest` methods. However,\nmethod parameters that are resolved by argument sources need to come first in the\nparameter list. Since a test class may contain regular tests as well as parameterized\ntests with different parameter lists, values from argument sources are not resolved for\nlifecycle methods (for example, `@BeforeEach`) and test class constructors.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/ParameterizedTestDemo.java[tags=ParameterResolver_example]\n----\n\n[[lifecycle-interop-classes]]\n=== Parameterized Classes\n\nEach invocation of a parameterized class has the same lifecycle as a regular test class.\nFor example, `@BeforeAll` methods will be executed _once_ before all invocations and\n`@BeforeEach` methods will be executed before each _test method_ invocation. Similar to\nxref:writing-tests/dynamic-tests.adoc[], invocations will appear one by one in the test tree of an\nIDE.\n\nYou may use `ParameterResolver` extensions with `@ParameterizedClass` constructors.\nHowever, if constructor injection is used, constructor parameters that are resolved by\nargument sources need to come first in the parameter list. Values from argument sources\nare not resolved for regular lifecycle methods (for example, `@BeforeEach`).\n\nIn addition to regular lifecycle methods, parameterized classes may declare\n`{BeforeParameterizedClassInvocation}` and `{AfterParameterizedClassInvocation}` lifecycle\nmethods that are called once before/after each invocation of the parameterized class.\nThese methods must be `static` unless the parameterized class is configured to use\n`@TestInstance(Lifecycle.PER_CLASS)` (see xref:writing-tests/test-instance-lifecycle.adoc[]).\n\nThese lifecycle methods may optionally declare parameters that are resolved depending on\nthe setting of the `injectArguments` annotation attribute. If it is set to `false`, the\nparameters must be resolved by other registered {ParameterResolver} extensions. If the\nattribute is set to `true` (the default), the method may declare parameters that match the\narguments of the parameterized class (see the Javadoc of\n`{BeforeParameterizedClassInvocation}` and `{AfterParameterizedClassInvocation}` for\ndetails). This may, for example, be used to initialize the used arguments as demonstrated\nby the following example.\n\n[source,java,indent=0]\n.Using parameterized class lifecycle methods\n----\ninclude::example$java/example/ParameterizedLifecycleDemo.java[tags=example]\n----\n<1> Initialization of the argument _before_ each invocation of the parameterized class\n<2> Usage of the previously initialized argument in a test method\n<3> Validation and cleanup of the argument _after_ each invocation of the parameterized\n class\n"
},
{
"path": "documentation/modules/ROOT/pages/writing-tests/repeated-tests.adoc",
"content": "= Repeated Tests\n\nJUnit Jupiter provides the ability to repeat a test a specified number of times by\nannotating a method with `@RepeatedTest` and specifying the total number of repetitions\ndesired. Each invocation of a repeated test behaves like the execution of a regular\n`@Test` method with full support for the same lifecycle callbacks and extensions.\n\nThe following example demonstrates how to declare a test named `repeatedTest()` that\nwill be automatically repeated 10 times.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java]\n----\n@RepeatedTest(10)\nvoid repeatedTest() {\n\t// ...\n}\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin]\n----\n@RepeatedTest(10)\nfun repeatedTest() {\n // ...\n}\n----\n--\n====\n\n`@RepeatedTest` can be configured with a failure threshold which signifies the number of\nfailures after which remaining repetitions will be automatically skipped. Set the\n`failureThreshold` attribute to a positive number less than the total number of\nrepetitions in order to skip the invocations of remaining repetitions after the specified\nnumber of failures has been encountered.\n\nFor example, if you are using `@RepeatedTest` to repeatedly invoke a test that you suspect\nto be _flaky_, a single failure is sufficient to demonstrate that the test is flaky, and\nthere is no need to invoke the remaining repetitions. To support that specific use case,\nset `failureThreshold = 1`. You can alternatively set the threshold to a number greater\nthan 1 depending on your use case.\n\nBy default, the `failureThreshold` attribute is set to `Integer.MAX_VALUE`, signaling that\nno failure threshold will be applied, which effectively means that the specified number of\nrepetitions will be invoked regardless of whether any repetitions fail.\n\nWARNING: If the repetitions of a `@RepeatedTest` method are executed in parallel, no\nguarantees can be made regarding the failure threshold. It is therefore recommended that a\n`@RepeatedTest` method be annotated with `@Execution(SAME_THREAD)` when parallel execution\nis configured. See xref:writing-tests/parallel-execution.adoc[] for further details.\n\nIn addition to specifying the number of repetitions and failure threshold, a custom\ndisplay name can be configured for each repetition via the `name` attribute of the\n`@RepeatedTest` annotation. Furthermore, the display name can be a pattern composed of a\ncombination of static text and dynamic placeholders. The following placeholders are\ncurrently supported.\n\n- `+{displayName}+`: display name of the `@RepeatedTest` method\n- `+{currentRepetition}+`: the current repetition count\n- `+{totalRepetitions}+`: the total number of repetitions\n\nThe default display name for a given repetition is generated based on the following\npattern: `\"repetition +{currentRepetition}+ of +{totalRepetitions}+\"`.Thus, the display\nnames for individual repetitions of the previous `repeatedTest()` example would be:\n`repetition 1 of 10`, `repetition 2 of 10`, etc.If you would like the display name of\nthe `@RepeatedTest` method included in the name of each repetition, you can define your\nown custom pattern or use the predefined `RepeatedTest.LONG_DISPLAY_NAME` pattern.The\nlatter is equal to `\"+{displayName}+ :: repetition +{currentRepetition}+ of\n+{totalRepetitions}+\"` which results in display names for individual repetitions like\n`repeatedTest() :: repetition 1 of 10`, `repeatedTest() :: repetition 2 of 10`, etc.\n\nIn order to retrieve information about the current repetition, the total number of\nrepetitions, the number of repetitions that have failed, and the failure threshold, a\ndeveloper can choose to have an instance of `{RepetitionInfo}` injected into a\n`@RepeatedTest`, `@BeforeEach`, or `@AfterEach` method.\n\n[[examples]]\n== Repeated Test Examples\n\nThe `RepeatedTestsDemo` class at the end of this section demonstrates several examples of\nrepeated tests.\n\nThe `repeatedTest()` method is identical to the example from the previous section; whereas,\n`repeatedTestWithRepetitionInfo()` demonstrates how to have an instance of\n`RepetitionInfo` injected into a test to access the total number of repetitions for the\ncurrent repeated test.\n\n`repeatedTestWithFailureThreshold()` demonstrates how to set a failure threshold and\nsimulates an unexpected failure for every second repetition.The resulting behavior can be\nviewed in the `ConsoleLauncher` output at the end of this section.\n\nThe next two methods demonstrate how to include a custom `@DisplayName` for the\n`@RepeatedTest` method in the display name of each repetition. `customDisplayName()`\ncombines a custom display name with a custom pattern and then uses `TestInfo` to verify\nthe format of the generated display name. `Repeat!` is the `+{displayName}+` which comes\nfrom the `@DisplayName` declaration, and `1/1` comes from\n`+{currentRepetition}+/+{totalRepetitions}+`.In contrast,\n`customDisplayNameWithLongPattern()` uses the aforementioned predefined\n`RepeatedTest.LONG_DISPLAY_NAME` pattern.\n\n`repeatedTestInGerman()` demonstrates the ability to translate display names of repeated\ntests into foreign languages -- in this case German, resulting in names for individual\nrepetitions such as: `Wiederholung 1 von 5`, `Wiederholung 2 von 5`, etc.\n\nSince the `beforeEach()` method is annotated with `@BeforeEach` it will get executed\nbefore each repetition of each repeated test. By having the `TestInfo` and\n`RepetitionInfo` injected into the method, we see that it's possible to obtain\ninformation about the currently executing repeated test. Executing `RepeatedTestsDemo`\nwith the `INFO` log level enabled results in the following output.\n\n....\nINFO: About to execute repetition 1 of 10 for repeatedTest\nINFO: About to execute repetition 2 of 10 for repeatedTest\nINFO: About to execute repetition 3 of 10 for repeatedTest\nINFO: About to execute repetition 4 of 10 for repeatedTest\nINFO: About to execute repetition 5 of 10 for repeatedTest\nINFO: About to execute repetition 6 of 10 for repeatedTest\nINFO: About to execute repetition 7 of 10 for repeatedTest\nINFO: About to execute repetition 8 of 10 for repeatedTest\nINFO: About to execute repetition 9 of 10 for repeatedTest\nINFO: About to execute repetition 10 of 10 for repeatedTest\nINFO: About to execute repetition 1 of 5 for repeatedTestWithRepetitionInfo\nINFO: About to execute repetition 2 of 5 for repeatedTestWithRepetitionInfo\nINFO: About to execute repetition 3 of 5 for repeatedTestWithRepetitionInfo\nINFO: About to execute repetition 4 of 5 for repeatedTestWithRepetitionInfo\nINFO: About to execute repetition 5 of 5 for repeatedTestWithRepetitionInfo\nINFO: About to execute repetition 1 of 8 for repeatedTestWithFailureThreshold\nINFO: About to execute repetition 2 of 8 for repeatedTestWithFailureThreshold\nINFO: About to execute repetition 3 of 8 for repeatedTestWithFailureThreshold\nINFO: About to execute repetition 4 of 8 for repeatedTestWithFailureThreshold\nINFO: About to execute repetition 1 of 1 for customDisplayName\nINFO: About to execute repetition 1 of 1 for customDisplayNameWithLongPattern\nINFO: About to execute repetition 1 of 5 for repeatedTestInGerman\nINFO: About to execute repetition 2 of 5 for repeatedTestInGerman\nINFO: About to execute repetition 3 of 5 for repeatedTestInGerman\nINFO: About to execute repetition 4 of 5 for repeatedTestInGerman\nINFO: About to execute repetition 5 of 5 for repeatedTestInGerman\n....\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/RepeatedTestsDemo.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/RepeatedTestsDemo.kt[tags=user_guide]\n----\n--\n====\n\nWhen using the `ConsoleLauncher` with the unicode theme enabled, execution of\n`RepeatedTestsDemo` results in the following output to the console.\n\n....\n├─ RepeatedTestsDemo ✔\n│ ├─ repeatedTest() ✔\n│ │ ├─ repetition 1 of 10 ✔\n│ │ ├─ repetition 2 of 10 ✔\n│ │ ├─ repetition 3 of 10 ✔\n│ │ ├─ repetition 4 of 10 ✔\n│ │ ├─ repetition 5 of 10 ✔\n│ │ ├─ repetition 6 of 10 ✔\n│ │ ├─ repetition 7 of 10 ✔\n│ │ ├─ repetition 8 of 10 ✔\n│ │ ├─ repetition 9 of 10 ✔\n│ │ └─ repetition 10 of 10 ✔\n│ ├─ repeatedTestWithRepetitionInfo(RepetitionInfo) ✔\n│ │ ├─ repetition 1 of 5 ✔\n│ │ ├─ repetition 2 of 5 ✔\n│ │ ├─ repetition 3 of 5 ✔\n│ │ ├─ repetition 4 of 5 ✔\n│ │ └─ repetition 5 of 5 ✔\n│ ├─ repeatedTestWithFailureThreshold(RepetitionInfo) ✔\n│ │ ├─ repetition 1 of 8 ✔\n│ │ ├─ repetition 2 of 8 ✘ Boom!\n│ │ ├─ repetition 3 of 8 ✔\n│ │ ├─ repetition 4 of 8 ✘ Boom!\n│ │ ├─ repetition 5 of 8 ↷ Failure threshold [2] exceeded\n│ │ ├─ repetition 6 of 8 ↷ Failure threshold [2] exceeded\n│ │ ├─ repetition 7 of 8 ↷ Failure threshold [2] exceeded\n│ │ └─ repetition 8 of 8 ↷ Failure threshold [2] exceeded\n│ ├─ Repeat! ✔\n│ │ └─ Repeat! 1/1 ✔\n│ ├─ Details... ✔\n│ │ └─ Details... :: repetition 1 of 1 ✔\n│ └─ repeatedTestInGerman() ✔\n│ ├─ Wiederholung 1 von 5 ✔\n│ ├─ Wiederholung 2 von 5 ✔\n│ ├─ Wiederholung 3 von 5 ✔\n│ ├─ Wiederholung 4 von 5 ✔\n│ └─ Wiederholung 5 von 5 ✔\n....\n"
},
{
"path": "documentation/modules/ROOT/pages/writing-tests/tagging-and-filtering.adoc",
"content": "= Tagging and Filtering\n\nTest classes and methods can be tagged via the `@Tag` annotation. Those tags can later be\nused to filter xref:running-tests/intro.adoc[test discovery and execution]. Please refer to the\nxref:running-tests/tags.adoc[] section for more information about tag support in the JUnit\nPlatform.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/TaggingDemo.java[tags=user_guide]\n----\n\nTIP: See xref:writing-tests/annotations.adoc#annotations[Meta-Annotations and Composed Annotations] for examples demonstrating how to create\ncustom annotations for tags.\n"
},
{
"path": "documentation/modules/ROOT/pages/writing-tests/test-classes-and-methods.adoc",
"content": "= Test Classes and Methods\n\nTest methods and lifecycle methods may be declared locally within the current test class,\ninherited from superclasses, or inherited from interfaces (see\nxref:writing-tests/test-interfaces-and-default-methods.adoc[]). In addition, test methods and\nlifecycle methods must not be `abstract` and must not return a value (except `@TestFactory`\nmethods which are required to return a value).\n\n[NOTE]\n.Class and method visibility\n====\nTest classes, test methods, and lifecycle methods are not required to be `public`, but\nthey must _not_ be `private`.\n\nIt is generally recommended to omit the `public` modifier for test classes, test methods,\nand lifecycle methods unless there is a technical reason for doing so – for example, when\na test class is extended by a test class in another package. Another technical reason for\nmaking classes and methods `public` is to simplify testing on the module path when using\nthe Java Module System.\n====\n\n[NOTE]\n.Field and method inheritance\n====\nFields in test classes are inherited. For example, a `@TempDir` field from a superclass\nwill always be applied in a subclass.\n\nTest methods and lifecycle methods are inherited unless they are overridden according to\nthe visibility rules of the Java language. For example, a `@Test` method from a superclass\nwill always be applied in a subclass unless the subclass explicitly overrides the method.\nSimilarly, if a package-private `@Test` method is declared in a superclass that resides in\na different package than the subclass, that `@Test` method will always be applied in the\nsubclass since the subclass cannot override a package-private method from a superclass in\na different package.\n\nSee also: xref:extensions/supported-utilities-in-extensions.adoc#search-semantics[Field and Method Search Semantics]\n====\n\nThe following test class demonstrates the use of `@Test` methods and all supported\nlifecycle methods. For further information on runtime semantics, see\nxref:writing-tests/test-execution-order.adoc[] and\nxref:extensions/relative-execution-order-of-user-code-and-extensions.adoc#wrapping-behavior[Wrapping Behavior of Callbacks].\n\n.A standard test class\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/StandardTests.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/StandardTests.kt[tags=user_guide]\n----\n--\n====\n\nIt is also possible to use Java `record` classes as test classes as illustrated by the\nfollowing example.\n\n[source,java,indent=0]\n.A test class written as a Java record\n----\ninclude::example$java/example/MyFirstJUnitJupiterRecordTests.java[tags=user_guide]\n----\n\n[[kotlin-coroutines]]\n== Kotlin Coroutines\n\nTest methods and lifecycle methods may be written in Kotlin and may optionally use the `suspend`\nkeyword for testing code using coroutines.\n\n[source,kotlin]\n.A test class written in Kotlin\n----\ninclude::example$kotlin/example/KotlinCoroutinesDemo.kt[tags=user_guide]\n----\n\nNOTE: Using suspending functions as test or lifecycle methods requires\nhttps://central.sonatype.com/artifact/org.jetbrains.kotlin/kotlin-stdlib[`kotlin-stdlib`],\nhttps://central.sonatype.com/artifact/org.jetbrains.kotlin/kotlin-reflect[`kotlin-reflect`],\nand\nhttps://central.sonatype.com/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core[`kotlinx-coroutines-core`]\nto be present on the classpath or module path.\n\nWhen using `suspend` test or lifecycle methods, JUnit internally uses `runBlocking` to execute them.\nThis is sufficient for simple coroutine-based tests.\n\nHowever, `runBlocking` does not support skipping calls to `delay` and does not provide control over\nvirtual time or dispatchers.\n\nAs an alternative, tests can be written as regular `@Test` methods and wrapped in `runTest` from\nhttps://central.sonatype.com/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-test[`kotlinx-coroutines-test`]\nto support skipping delays during tests and gain control over virtual time and dispatchers.\n\n[source,kotlin]\n----\ninclude::example$kotlin/example/KotlinCoroutinesRunTestDemo.kt[tags=user_guide]\n----\n"
},
{
"path": "documentation/modules/ROOT/pages/writing-tests/test-execution-order.adoc",
"content": "= Test Execution Order\n\nBy default, test classes and methods will be ordered using an algorithm that is\ndeterministic but intentionally nonobvious. This ensures that subsequent runs of a test\nsuite execute test classes and test methods in the same order, thereby allowing for\nrepeatable builds.\n\nNOTE: See xref:writing-tests/definitions.adoc[] for a definition of _test method_ and _test class_.\n\n[[methods]]\n== Method Order\n\nAlthough true _unit tests_ typically should not rely on the order in which they are\nexecuted, there are times when it is necessary to enforce a specific test method execution\norder -- for example, when writing _integration tests_ or _functional tests_ where the\nsequence of the tests is important, especially in conjunction with\n`@TestInstance(Lifecycle.PER_CLASS)`.\n\nTo control the order in which test methods are executed, annotate your test class or test\ninterface with `{TestMethodOrder}` and specify the desired `{MethodOrderer}`\nimplementation. You can implement your own custom `MethodOrderer` or use one of the\nfollowing built-in `MethodOrderer` implementations.\n\n* `{MethodOrderer_DisplayName}`: sorts test methods _alphanumerically_ based on their\n display names (see xref:writing-tests/display-names.adoc#generator-precedence-rules[display name\n generation precedence rules])\n* `{MethodOrderer_MethodName}`: sorts test methods _alphanumerically_ based on their names\n and formal parameter lists\n* `{MethodOrderer_OrderAnnotation}`: sorts test methods _numerically_ based on values\n specified via the `{Order}` annotation\n* `{MethodOrderer_Random}`: orders test methods _pseudo-randomly_ and supports\n configuration of a custom _seed_\n\nThe `MethodOrderer` configured on a test class is inherited by the `@Nested` test classes\nit contains, recursively. If you want to avoid that a `@Nested` test class uses the same\n`MethodOrderer` as its enclosing class, you can specify `{MethodOrderer_Default}` together\nwith `{TestMethodOrder}`.\n\nNOTE: See also: xref:extensions/relative-execution-order-of-user-code-and-extensions.adoc#wrapping-behavior[Wrapping Behavior of Callbacks]\n\nThe following example demonstrates how to guarantee that test methods are executed in the\norder specified via the `@Order` annotation.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/OrderedTestsDemo.java[tags=user_guide]\n----\n\n[[methods-default]]\n=== Setting the Default Method Orderer\n\nYou can use the `junit.jupiter.testmethod.order.default` xref:running-tests/configuration-parameters.adoc[configuration parameter] to specify the fully qualified class name of the\n`{MethodOrderer}` you would like to use by default. Just like for the orderer configured\nvia the `{TestMethodOrder}` annotation, the supplied class has to implement the\n`MethodOrderer` interface. The default orderer will be used for all tests unless the\n`@TestMethodOrder` annotation is present on an enclosing test class or test interface.\n\nFor example, to use the `{MethodOrderer_OrderAnnotation}` method orderer by default, you\nshould set the configuration parameter to the corresponding fully qualified class name\n(e.g., in `src/test/resources/junit-platform.properties`):\n\n[source,properties,indent=0]\n----\njunit.jupiter.testmethod.order.default = \\\n org.junit.jupiter.api.MethodOrderer$OrderAnnotation\n----\n\nSimilarly, you can specify the fully qualified name of any custom class that implements\n`MethodOrderer`.\n\n[[classes]]\n== Class Order\n\nAlthough test classes typically should not rely on the order in which they are executed,\nthere are times when it is desirable to enforce a specific test class execution order. You\nmay wish to execute test classes in a random order to ensure there are no accidental\ndependencies between test classes, or you may wish to order test classes to optimize build\ntime as outlined in the following scenarios.\n\n* Run previously failing tests and faster tests first: \"fail fast\" mode\n* With parallel execution enabled, schedule longer tests first: \"shortest test plan\n execution duration\" mode\n* Various other use cases\n\nTo configure test class execution order _globally_ for the entire test suite, use the\n`junit.jupiter.testclass.order.default` xref:running-tests/configuration-parameters.adoc[configuration\nparameter] to specify the fully qualified class name of the `{ClassOrderer}` you would\nlike to use. The supplied class must implement the `ClassOrderer` interface.\n\nYou can implement your own custom `ClassOrderer` or use one of the following built-in\n`ClassOrderer` implementations.\n\n* `{ClassOrderer_ClassName}`: sorts test classes _alphanumerically_ based on their fully\n qualified class names\n* `{ClassOrderer_DisplayName}`: sorts test classes _alphanumerically_ based on their\n display names (see xref:writing-tests/display-names.adoc#generator-precedence-rules[display name\n generation precedence rules])\n* `{ClassOrderer_OrderAnnotation}`: sorts test classes _numerically_ based on values\n specified via the `{Order}` annotation\n* `{ClassOrderer_Random}`: orders test classes _pseudo-randomly_ and supports\n configuration of a custom _seed_\n\nFor example, for the `@Order` annotation to be honored on _test classes_, you should\nconfigure the `{ClassOrderer_OrderAnnotation}` class orderer using the configuration\nparameter with the corresponding fully qualified class name (e.g., in\n`src/test/resources/junit-platform.properties`):\n\n[source,properties,indent=0]\n----\njunit.jupiter.testclass.order.default = \\\n org.junit.jupiter.api.ClassOrderer$OrderAnnotation\n----\n\nThe configured `ClassOrderer` will be applied to all top-level test classes (including\n`static` nested test classes) and `@Nested` test classes.\n\nNOTE: Top-level test classes will be ordered relative to each other; whereas, `@Nested`\ntest classes will be ordered relative to other `@Nested` test classes sharing the same\n_enclosing class_.\n\nTo configure test class execution order _locally_ for `@Nested` test classes, declare the\n`{TestClassOrder}` annotation on the enclosing class for the `@Nested` test classes you\nwant to order, and supply a class reference to the `ClassOrderer` implementation you would\nlike to use directly in the `@TestClassOrder` annotation. The configured `ClassOrderer`\nwill be applied recursively to `@Nested` test classes and their `@Nested` test classes.\nIf you want to avoid that a `@Nested` test class uses the same `ClassOrderer` as its\nenclosing class, you can specify `{ClassOrderer_Default}` together with `@TestClassOrder`.\nNote that a local `@TestClassOrder` declaration always overrides an inherited\n`@TestClassOrder` declaration or a `ClassOrderer` configured globally via the\n`junit.jupiter.testclass.order.default` configuration parameter.\n\nThe following example demonstrates how to guarantee that `@Nested` test classes are\nexecuted in the order specified via the `@Order` annotation.\n\n[source,java,indent=0]\n----\ninclude::example$java/example/OrderedNestedTestClassesDemo.java[tags=user_guide]\n----\n"
},
{
"path": "documentation/modules/ROOT/pages/writing-tests/test-instance-lifecycle.adoc",
"content": "= Test Instance Lifecycle\n\nIn order to allow individual test methods to be executed in isolation and to avoid\nunexpected side effects due to mutable test instance state, JUnit creates a new instance\nof each test class before executing each _test method_ (see\nxref:writing-tests/definitions.adoc[]). This \"per-method\" test instance lifecycle is the default\nbehavior in JUnit Jupiter and is analogous to all previous versions of JUnit.\n\nNOTE: Please note that the test class will still be instantiated if a given _test method_\nis _disabled_ via a xref:writing-tests/conditional-test-execution.adoc[condition] (e.g., `@Disabled`,\n`@DisabledOnOs`, etc.) even when the \"per-method\" test instance lifecycle mode is active.\n\nIf you would prefer that JUnit Jupiter execute all test methods on the same test\ninstance, annotate your test class with `@TestInstance(Lifecycle.PER_CLASS)`. When using\nthis mode, a new test instance will be created once per test class. Thus, if your test\nmethods rely on state stored in instance variables, you may need to reset that state in\n`@BeforeEach` or `@AfterEach` methods.\n\nThe \"per-class\" mode has some additional benefits over the default \"per-method\" mode.\nSpecifically, with the \"per-class\" mode it becomes possible to declare `@BeforeAll` and\n`@AfterAll` on non-static methods as well as on interface `default` methods.\n\nIf you are authoring tests using the Kotlin programming language, you may also find it\neasier to implement non-static `@BeforeAll` and `@AfterAll` lifecycle methods as well as\n`@MethodSource` factory methods by switching to the \"per-class\" test instance lifecycle\nmode.\n\n[[default]]\n== Changing the Default Test Instance Lifecycle\n\nIf a test class or test interface is not annotated with `@TestInstance`, JUnit Jupiter\nwill use a _default_ lifecycle mode. The standard _default_ mode is `PER_METHOD`;\nhowever, it is possible to change the _default_ for the execution of an entire test plan.\nTo change the default test instance lifecycle mode, set the\n`junit.jupiter.testinstance.lifecycle.default` _configuration parameter_ to the name of\nan enum constant defined in `TestInstance.Lifecycle`, ignoring case. This can be supplied\nas a JVM system property, as a _configuration parameter_ in the\n`LauncherDiscoveryRequest` that is passed to the `Launcher`, or via the JUnit Platform\nconfiguration file (see xref:running-tests/configuration-parameters.adoc[] for details).\n\nFor example, to set the default test instance lifecycle mode to `Lifecycle.PER_CLASS`,\nyou can start your JVM with the following system property.\n\n`-Djunit.jupiter.testinstance.lifecycle.default=per_class`\n\nNote, however, that setting the default test instance lifecycle mode via the JUnit\nPlatform configuration file is a more robust solution since the configuration file can be\nchecked into a version control system along with your project and can therefore be used\nwithin IDEs and your build software.\n\nTo set the default test instance lifecycle mode to `Lifecycle.PER_CLASS` via the JUnit\nPlatform configuration file, create a file named `junit-platform.properties` in the root\nof the class path (e.g., `src/test/resources`) with the following content.\n\n`junit.jupiter.testinstance.lifecycle.default = per_class`\n\nWARNING: Changing the _default_ test instance lifecycle mode can lead to unpredictable\nresults and fragile builds if not applied consistently. For example, if the build\nconfigures \"per-class\" semantics as the default but tests in the IDE are executed using\n\"per-method\" semantics, that can make it difficult to debug errors that occur on the\nbuild server. It is therefore recommended to change the default in the JUnit Platform\nconfiguration file instead of via a JVM system property.\n"
},
{
"path": "documentation/modules/ROOT/pages/writing-tests/test-interfaces-and-default-methods.adoc",
"content": "= Test Interfaces and Default Methods\n\nJUnit Jupiter allows `@Test`, `@RepeatedTest`, `@ParameterizedTest`, `@TestFactory`,\n`@TestTemplate`, `@BeforeEach`, and `@AfterEach` to be declared on interface `default`\nmethods. `@BeforeAll` and `@AfterAll` can either be declared on `static` methods in a\ntest interface or on interface `default` methods _if_ the test interface or test class is\nannotated with `@TestInstance(Lifecycle.PER_CLASS)` (see\nxref:writing-tests/test-instance-lifecycle.adoc[]). Here are some examples.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/testinterface/TestLifecycleLogger.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/testinterface/TestLifecycleLogger.kt[tags=user_guide]\n----\n--\n====\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/testinterface/TestInterfaceDynamicTestsDemo.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/testinterface/TestInterfaceDynamicTestsDemo.kt[tags=user_guide]\n----\n--\n====\n\n`@ExtendWith` and `@Tag` can be declared on a test interface so that classes that\nimplement the interface automatically inherit its tags and extensions. See\nxref:extensions/test-lifecycle-callbacks.adoc#before-after-execution[Before and After Test Execution Callbacks] for the source code of the\nxref:extensions/test-lifecycle-callbacks.adoc#timing-extension[TimingExtension].\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/testinterface/TimeExecutionLogger.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/testinterface/TimeExecutionLogger.kt[tags=user_guide]\n----\n--\n====\n\nIn your test class you can then implement these test interfaces to have them applied.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/testinterface/TestInterfaceDemo.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/testinterface/TestInterfaceDemo.kt[tags=user_guide]\n----\n--\n====\n\nRunning the `TestInterfaceDemo` results in output similar to the following:\n\n....\nINFO example.TestLifecycleLogger - Before all tests\nINFO example.TestLifecycleLogger - About to execute [dynamicTestsForPalindromes()]\nINFO example.TimingExtension - Method [dynamicTestsForPalindromes] took 19 ms.\nINFO example.TestLifecycleLogger - Finished executing [dynamicTestsForPalindromes()]\nINFO example.TestLifecycleLogger - About to execute [isEqualValue()]\nINFO example.TimingExtension - Method [isEqualValue] took 1 ms.\nINFO example.TestLifecycleLogger - Finished executing [isEqualValue()]\nINFO example.TestLifecycleLogger - After all tests\n....\n\nAnother possible application of this feature is to write tests for interface contracts.\nFor example, you can write tests for how implementations of `Object.equals` or\n`Comparable.compareTo` should behave as follows.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/defaultmethods/Testable.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/defaultmethods/Testable.kt[tags=user_guide]\n----\n--\n====\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/defaultmethods/EqualsContract.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/defaultmethods/EqualsContract.kt[tags=user_guide]\n----\n--\n====\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/defaultmethods/ComparableContract.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/defaultmethods/ComparableContract.kt[tags=user_guide]\n----\n--\n====\n\nIn your test class you can then implement both contract interfaces thereby inheriting the\ncorresponding tests. Of course you'll have to implement the abstract methods.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java,indent=0]\n----\ninclude::example$java/example/defaultmethods/StringTests.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin,indent=0]\n----\ninclude::example$kotlin/example/kotlin/defaultmethods/StringTests.kt[tags=user_guide]\n----\n--\n====\n\nNOTE: The above tests are merely meant as examples and therefore not complete.\n"
},
{
"path": "documentation/modules/ROOT/pages/writing-tests/test-templates.adoc",
"content": "= Test Templates\n\nA `{TestTemplate}` method is not a regular test case but rather a template for a test\ncase. As such, it is designed to be invoked multiple times depending on the number of\ninvocation contexts returned by the registered providers. Thus, it must be used in\nconjunction with a registered `{TestTemplateInvocationContextProvider}` extension. Each\ninvocation of a test template method behaves like the execution of a regular `@Test`\nmethod with full support for the same lifecycle callbacks and extensions. Please refer to\nxref:extensions/providing-invocation-contexts-for-test-templates.adoc[] for usage examples.\n\nNOTE: xref:writing-tests/repeated-tests.adoc[] and\nxref:writing-tests/parameterized-classes-and-tests.adoc[Parameterized Tests] are built-in specializations of\ntest templates.\n"
},
{
"path": "documentation/modules/ROOT/pages/writing-tests/timeouts.adoc",
"content": "= Timeouts\n\nThe `@Timeout` annotation allows one to declare that a test, test factory, test template,\nor lifecycle method should fail if its execution time exceeds a given duration. The time\nunit for the duration defaults to seconds but is configurable.\n\nThe following example shows how `@Timeout` is applied to lifecycle and test methods.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java]\n----\ninclude::example$java/example/TimeoutDemo.java[tags=user_guide]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin]\n----\ninclude::example$kotlin/example/kotlin/TimeoutDemo.kt[tags=user_guide]\n----\n--\n====\n\nTo apply the same timeout to all test methods within a test class and all of its `@Nested`\nclasses, you can declare the `@Timeout` annotation at the class level. It will then be\napplied to all test, test factory, and test template methods within that class and its\n`@Nested` classes unless overridden by a `@Timeout` annotation on a specific method or\n`@Nested` class. Please note that `@Timeout` annotations declared at the class level are\nnot applied to lifecycle methods.\n\nDeclaring `@Timeout` on a `@TestFactory` method checks that the factory method returns\nwithin the specified duration but does not verify the execution time of each individual\n`DynamicTest` generated by the factory. Please use\n`assertTimeout()` or `assertTimeoutPreemptively()` for that purpose.\n\nIf `@Timeout` is present on a `@TestTemplate` method — for example, a `@RepeatedTest` or\n`@ParameterizedTest` — each invocation will have the given timeout applied to it.\n\n[[thread-mode]]\n== Thread mode\n\nThe timeout can be applied using one of the following three thread modes: `SAME_THREAD`,\n`SEPARATE_THREAD`, or `INFERRED`.\n\nWhen `SAME_THREAD` is used, the execution of the annotated method proceeds in the main\nthread of the test. If the timeout is exceeded, the main thread is interrupted from\nanother thread. This is done to ensure interoperability with frameworks such as Spring\nthat make use of mechanisms that are sensitive to the currently running thread — for\nexample, `ThreadLocal` transaction management.\n\nOn the contrary when `SEPARATE_THREAD` is used, like the `assertTimeoutPreemptively()`\nassertion, the execution of the annotated method proceeds in a separate thread, this\ncan lead to undesirable side effects, see xref:writing-tests/assertions.adoc#preemptive-timeouts[Preemptive Timeouts with `assertTimeoutPreemptively()`].\n\nWhen `INFERRED` (default) thread mode is used, the thread mode is resolved via the\n`junit.jupiter.execution.timeout.thread.mode.default` configuration parameter. If the\nprovided configuration parameter is invalid or not present then `SAME_THREAD` is used as\nfallback.\n\n[[default-timeouts]]\n== Default Timeouts\n\nThe following xref:running-tests/configuration-parameters.adoc[configuration parameters] can be used to\nspecify default timeouts for all methods of a certain category unless they or an enclosing\ntest class is annotated with `@Timeout`:\n\n`junit.jupiter.execution.timeout.default`::\n Default timeout for all testable and lifecycle methods\n`junit.jupiter.execution.timeout.testable.method.default`::\n Default timeout for all testable methods\n`junit.jupiter.execution.timeout.test.method.default`::\n Default timeout for `@Test` methods\n`junit.jupiter.execution.timeout.testtemplate.method.default`::\n Default timeout for `@TestTemplate` methods\n`junit.jupiter.execution.timeout.testfactory.method.default`::\n Default timeout for `@TestFactory` methods\n`junit.jupiter.execution.timeout.lifecycle.method.default`::\n Default timeout for all lifecycle methods\n`junit.jupiter.execution.timeout.beforeall.method.default`::\n Default timeout for `@BeforeAll` methods\n`junit.jupiter.execution.timeout.beforeeach.method.default`::\n Default timeout for `@BeforeEach` methods\n`junit.jupiter.execution.timeout.aftereach.method.default`::\n Default timeout for `@AfterEach` methods\n`junit.jupiter.execution.timeout.afterall.method.default`::\n Default timeout for `@AfterAll` methods\n\nMore specific configuration parameters override less specific ones. For example,\n`junit.jupiter.execution.timeout.test.method.default` overrides\n`junit.jupiter.execution.timeout.testable.method.default` which overrides\n`junit.jupiter.execution.timeout.default`.\n\nThe values of such configuration parameters must be in the following, case-insensitive\nformat: ` [ns|μs|ms|s|m|h|d]`. The space between the number and the unit may be\nomitted. Specifying no unit is equivalent to using seconds.\n\n.Example timeout configuration parameter values\n[cols=\"20,80\"]\n|===\n| Parameter value | Equivalent annotation\n\n| `42` | `@Timeout(42)`\n| `42 ns` | `@Timeout(value = 42, unit = NANOSECONDS)`\n| `42 μs` | `@Timeout(value = 42, unit = MICROSECONDS)`\n| `42 ms` | `@Timeout(value = 42, unit = MILLISECONDS)`\n| `42 s` | `@Timeout(value = 42, unit = SECONDS)`\n| `42 m` | `@Timeout(value = 42, unit = MINUTES)`\n| `42 h` | `@Timeout(value = 42, unit = HOURS)`\n| `42 d` | `@Timeout(value = 42, unit = DAYS)`\n|===\n\n\n[[polling]]\n== Using @Timeout for Polling Tests\n\nWhen dealing with asynchronous code, it is common to write tests that poll while waiting\nfor something to happen before performing any assertions. In some cases you can rewrite\nthe logic to use a `CountDownLatch` or another synchronization mechanism, but sometimes\nthat is not possible — for example, if the subject under test sends a message to a channel\nin an external message broker and assertions cannot be performed until the message has\nbeen successfully sent through the channel. Asynchronous tests like these require some\nform of timeout to ensure they don't hang the test suite by executing indefinitely, as\nwould be the case if an asynchronous message never gets successfully delivered.\n\nBy configuring a timeout for an asynchronous test that polls, you can ensure that the test\ndoes not execute indefinitely. The following example demonstrates how to achieve this with\nJUnit Jupiter's `@Timeout` annotation. This technique can be used to implement \"poll\nuntil\" logic very easily.\n\n[tabs]\n====\nJava::\n+\n--\n[source,java]\n----\ninclude::example$java/example/PollingTimeoutDemo.java[tags=user_guide,indent=0]\n----\n--\n\nKotlin::\n+\n--\n[source,kotlin]\n----\ninclude::example$kotlin/example/kotlin/PollingTimeoutDemo.kt[tags=user_guide,indent=0]\n----\n--\n====\n\nNOTE: If you need more control over polling intervals and greater flexibility with\nasynchronous tests, consider using a dedicated library such as\nlink:https://github.com/awaitility/awaitility[Awaitility].\n\n\n[[debugging]]\n== Debugging Timeouts\n\nRegistered xref:extensions/pre-interrupt-callback.adoc[] extensions are called prior to invoking\n`Thread.interrupt()` on the thread that is executing the timed out method. This allows to\ninspect the application state and output additional information that might be helpful for\ndiagnosing the cause of a timeout.\n\n\n[[debugging-thread-dump]]\n=== Thread Dump on Timeout\n\nJUnit registers a default implementation of the xref:extensions/pre-interrupt-callback.adoc[]\nextension point that dumps the stacks of all threads to `System.out` if enabled by setting\nthe `junit.jupiter.execution.timeout.threaddump.enabled`\nxref:running-tests/configuration-parameters.adoc[configuration parameter] to `true`.\n\n\n[[mode]]\n== Disable @Timeout Globally\n\nWhen stepping through your code in a debug session, a fixed timeout limit may influence\nthe result of the test, e.g. mark the test as failed although all assertions were met.\n\nJUnit Jupiter supports the `junit.jupiter.execution.timeout.mode` configuration parameter\nto configure when timeouts are applied. There are three modes: `enabled`, `disabled`,\nand `disabled_on_debug`. The default mode is `enabled`.\nA VM runtime is considered to run in debug mode when one of its input parameters starts\nwith `-agentlib:jdwp` or `-Xrunjdwp`.\nThis heuristic is queried by the `disabled_on_debug` mode.\n"
},
{
"path": "documentation/modules/ROOT/partials/release-notes/release-notes-6.0.0.adoc",
"content": "[[v6.0.0]]\n== 6.0.0\n\n*Date of Release:* September 30, 2025\n\n*Scope:*\n\n* Java 17 and Kotlin 2.1 baseline\n* Single version number for Platform, Jupiter, and Vintage\n* Use of JSpecify annotations to express nullability\n* Integration of JFR functionality in `junit-platform-launcher`\n* Removal of `junit-platform-runner` and `junit-platform-jfr`\n* Deterministic order of `@Nested` classes\n* `MethodOrderer.Default` and `ClassOrderer.Default` for `@Nested` classes\n* Inheritance of `@TestMethodOrder` by enclosed `@Nested` classes\n* Switch to FastCSV library for `@CsvSource` and `@CsvFileSource`\n* Support for using Kotlin `suspend` functions as test methods\n* New `--fail-fast` mode for ConsoleLauncher\n* Support for cancelling test execution via `CancellationToken`\n* Removal of various deprecated behaviors and APIs\n\nFor complete details consult the\nhttps://docs.junit.org/6.0.0/release-notes.html[6.0.0 Release Notes] online.\n"
},
{
"path": "documentation/modules/ROOT/partials/release-notes/release-notes-6.0.1.adoc",
"content": "[[v6.0.1]]\n== 6.0.1\n\n*Date of Release:* October 31, 2025\n\n*Scope:* Bug fixes and enhancements since 6.0.0\n\nFor a complete list of all _closed_ issues and pull requests for this release, consult the\nlink:{junit-framework-repo}+/milestone/110?closed=1+[6.0.1] milestone page in the JUnit\nrepository on GitHub.\n\n\n[[v6.0.1-junit-platform]]\n=== JUnit Platform\n\n[[v6.0.1-junit-platform-bug-fixes]]\n==== Bug Fixes\n\n* The `jdk.jfr` package is now an optional import when using the `junit-platform-launcher`\n as an OSGi bundle.\n\n[[v6.0.1-junit-platform-new-features-and-improvements]]\n==== New Features and Improvements\n\n* Legacy documentation regarding Java 8 compatibility has been removed from the User Guide.\n\n\n[[v6.0.1-junit-jupiter]]\n=== JUnit Jupiter\n\n[[v6.0.1-junit-jupiter-bug-fixes]]\n==== Bug Fixes\n\n* A regression introduced in version 6.0.0 caused an exception when using `@CsvSource` or\n `@CsvFileSource` if the `delimiter` or `delimiterString` attribute was set to `+++#+++`.\n This occurred because `+++#+++` was used as the default comment character without an\n option to change it. To resolve this, a new `commentCharacter` attribute has been added\n to both annotations. Its default value remains `+++#+++`, but it can now be customized\n to avoid conflicts with other control characters.\n* Fix `IllegalAccessError` thrown when using the Kotlin-specific `assertDoesNotThrow`\n assertion.\n* Stop reporting discovery issues for synthetic methods, particularly in conjunction with\n Kotlin suspend functions.\n* Fix support for test methods with the same signature as package-private methods declared\n in super classes in different packages.\n\n[[v6.0.1-junit-jupiter-deprecations-and-breaking-changes]]\n==== Deprecations and Breaking Changes\n\n* The `org.junit.jupiter.migrationsupport` module descriptor has been marked as deprecated\n for removal.\n\n[[v6.0.1-junit-jupiter-new-features-and-improvements]]\n==== New Features and Improvements\n\n* The `@CsvSource` and `@CsvFileSource` annotations now allow specifying a custom comment\n character using the new `commentCharacter` attribute.\n* Improve error message when `@ParameterizedClass` is used with field injection without\n providing enough arguments.\n* Allow calling the `TypedArgumentConverter` constructor for `@Nullable T` target types\n without having to cast class literals to `Class<@Nullable T>`.\n\n\n[[v6.0.1-junit-vintage]]\n=== JUnit Vintage\n\n[[v6.0.1-junit-vintage-new-features-and-improvements]]\n==== New Features and Improvements\n\n* Allow disabling the reporting of discovery issues by the JUnit Vintage engine (including\n the one reported for its deprecation) by setting the new\n `junit.vintage.discovery.issue.reporting.enabled` configuration parameter to `false`.\n"
},
{
"path": "documentation/modules/ROOT/partials/release-notes/release-notes-6.0.2.adoc",
"content": "[[v6.0.2]]\n== 6.0.2\n\n*Date of Release:* January 6, 2026\n\n*Scope:* Bug fixes and enhancements since 6.0.1\n\nFor a complete list of all _closed_ issues and pull requests for this release, consult the\nlink:{junit-framework-repo}+/milestone/113?closed=1+[6.0.2] milestone page in the JUnit\nrepository on GitHub.\n\n\n[[v6.0.2-junit-platform]]\n=== JUnit Platform\n\n[[v6.0.2-junit-platform-bug-fixes]]\n==== Bug Fixes\n\n* Make `ConsoleLauncher` compatible with JDK 26 by avoiding final field mutations.\n* Enable recursive updates when using `NamespacedHierarchicalStore.computeIfAbsent(N, K, Function)`.\n This provides parity with the deprecated `NamespacedHierarchicalStore.getOrComputeIfAbsent(N, K, Function)`\n\n\n[[v6.0.2-junit-jupiter]]\n=== JUnit Jupiter\n\n[[v6.0.2-junit-jupiter-bug-fixes]]\n==== Bug Fixes\n\n* Allow using `@ResourceLock` on classes annotated with `@ClassTemplate` (or\n `@ParameterizedClass`).\n* Change API status of recommended method in `ArgumentsProvider` as well as\n `ParameterDeclaration(s)` as \"maintained\" rather than \"experimental\".\n\n\n[[v6.0.2-junit-vintage]]\n=== JUnit Vintage\n\nNo changes.\n"
},
{
"path": "documentation/modules/ROOT/partials/release-notes/release-notes-6.0.3.adoc",
"content": "[[v6.0.3]]\n== 6.0.3\n\n*Date of Release:* February 15, 2026\n\n*Scope:* Bug fixes and enhancements since 6.0.2\n\nFor a complete list of all _closed_ issues and pull requests for this release, consult the\nlink:{junit-framework-repo}+/milestone/116?closed=1+[6.0.3] milestone page in the JUnit\nrepository on GitHub.\n\n\n[[v6.0.3-junit-platform]]\n=== JUnit Platform\n\n[[v6.0.3-junit-platform-bug-fixes]]\n==== Bug Fixes\n\n* A deadlock issue in `NamespacedHierarchicalStore.computeIfAbsent(N, K, Function)` has\n been fixed.\n\n\n[[v6.0.3-junit-jupiter]]\n=== JUnit Jupiter\n\n[[v6.0.3-junit-jupiter-bug-fixes]]\n==== Bug Fixes\n\n* `@EnabledOnJre` and `@DisabledOnJre` once again work reliably when used with `JRE.OTHER`\n in a test running on a Java runtime whose version is higher than the version of the last\n `JAVA_*` constant in the `JRE` enum.\n\n\n[[v6.0.3-junit-vintage]]\n=== JUnit Vintage\n\nNo changes.\n"
},
{
"path": "documentation/modules/ROOT/partials/release-notes/release-notes-6.1.0-M1.adoc",
"content": "[[v6.1.0-M1]]\n== 6.1.0-M1\n\n*Date of Release:* November 17, 2025\n\n*Scope:*\n\n* New `org.junit.start` module for usage in compact source files\n* Execution mode configuration support for dynamic tests and containers\n* New parallel test executor implementation\n\nFor a complete list of all _closed_ issues and pull requests for this release, consult the\nlink:{junit-framework-repo}+/milestone/104?closed=1+[6.1.0-M1] milestone page in the JUnit\nrepository on GitHub.\n\n\n[[v6.1.0-M1-junit-platform]]\n=== JUnit Platform\n\n[[v6.1.0-M1-junit-platform-deprecations-and-breaking-changes]]\n==== Deprecations and Breaking Changes\n\n* Deprecate constructors for `ForkJoinPoolHierarchicalTestExecutorService` in favor of the\n new `ParallelHierarchicalTestExecutorServiceFactory` that also supports\n `WorkerThreadPoolHierarchicalTestExecutorService`.\n\n[[v6.1.0-M1-junit-platform-new-features-and-improvements]]\n==== New Features and Improvements\n\n* Support for creating a `ModuleSelector` from a `java.lang.Module` and using\n its classloader for test discovery.\n* New `WorkerThreadPoolHierarchicalTestExecutorService` implementation used for parallel\n test execution that is backed by a regular thread pool rather than a `ForkJoinPool`.\n Engine authors should switch to use `ParallelHierarchicalTestExecutorServiceFactory`\n rather than instantiating a concrete `HierarchicalTestExecutorService` implementation\n for parallel execution directly.\n* `OpenTestReportGeneratingListener` now supports redirecting XML events to a socket via\n the new `junit.platform.reporting.open.xml.socket` configuration parameter. When set to a\n port number, events are sent to `127.0.0.1:` instead of being written to a file.\n* Allow implementations of `HierarchicalTestEngine` to specify which nodes require the\n global read lock by overriding the `Node.isGlobalReadLockRequired()` method to return\n `false`.\n\n\n[[v6.1.0-M1-junit-jupiter]]\n=== JUnit Jupiter\n\n[[v6.1.0-M1-junit-jupiter-new-features-and-improvements]]\n==== New Features and Improvements\n\n* Introduce new module `org.junit.start` for writing and running tests. It simplifies\n using JUnit in compact source files together with a single `module import` statement.\n Find an example at the xref:running-tests/source-launcher.adoc[User Guide].\n* Introduce new `dynamicTest(Consumer)` factory method for dynamic\n tests. It allows configuring the `ExecutionMode` of the dynamic test in addition to its\n display name, test source URI, and executable.\n* Introduce new `dynamicContainer(Consumer)` factory method for\n dynamic containers. It allows configuring the `ExecutionMode` of the dynamic container\n and/or its children in addition to its display name, test source URI, and children.\n* Enrich `assertInstanceOf` failure using the test subject `Throwable` as cause. It\n results in the stack trace of the test subject `Throwable` to get reported along with\n the failure.\n* Make implementation of `HierarchicalTestExecutorService` used for parallel test\n execution configurable via the new\n `junit.jupiter.execution.parallel.config.executor-service` configuration parameter to\n in order to add support for `WorkerThreadPoolHierarchicalTestExecutorService`. Please\n refer to the\n xref:writing-tests/parallel-execution.adoc#config-executor-service[User Guide]\n for details.\n\n[[v6.1.0-M1-junit-vintage]]\n=== JUnit Vintage\n\nNo changes.\n"
},
{
"path": "documentation/modules/ROOT/partials/release-notes/release-notes-6.1.0-RC1.adoc",
"content": "[[v6.1.0-RC1]]\n== 6.1.0-RC1\n\n*Date of Release:* April 25, 2026\n\n*Scope:*\n\n* New `@DefaultLocale` and `@DefaultTimeZone` built-in extensions\n* New built-in extension for clearing/setting/restoring system properties\n* Configurable deletion strategy for `@TempDir` that allows ignoring failures\n* Improved stack trace pruning for assertion failures\n* New `org.junit.jupiter.api.Constants` class for referencing configuration parameters\n* Improvements to legacy XML reports for parameterized test classes\n* New experimental memory cleanup mode for large test suites\n\nFor a complete list of all _closed_ issues and pull requests for this release, consult the\nlink:{junit-framework-repo}+/milestone/112?closed=1+[6.1.0-RC1] milestone page in the JUnit\nrepository on GitHub.\n\n\n[[v6.1.0-RC1-junit-platform]]\n=== JUnit Platform\n\n[[v6.1.0-RC1-junit-platform-bug-fixes]]\n==== Bug Fixes\n\n* A deadlock issue in `NamespacedHierarchicalStore.computeIfAbsent(N, K, Function)` has\n been fixed.\n* `WorkerThreadPoolHierarchicalTestExecutorService` now rechecks the _done_ condition\n before rejecting an extraneous worker.\n* Missing precondition checks have been added to `Launcher` implementations.\n* Failures to resolve selectors are now propagated by the Suite Engine.\n\n[[v6.1.0-RC1-junit-platform-deprecations-and-breaking-changes]]\n==== Deprecations and Breaking Changes\n\n* In the `EngineTestKit`, `Executions.started()` has been deprecated in favor of\n `Executions.finished()`, since started executions are always finished.\n\n[[v6.1.0-RC1-junit-platform-new-features-and-improvements]]\n==== New Features and Improvements\n\n* `TestDescriptor` implementation requirements have now been clarified in the\n corresponding Javadoc.\n* The `UniqueId.uniqueIdFormat` field has been removed, reducing the size of `UniqueId`\n objects.\n* New `selectClasspathResources(String...)` and `selectClasspathResources(List)`\n** `Arguments.argumentsFrom(Iterable)` (alias for `of(Iterable)`)\n** `Arguments.argumentSetFrom(String, Iterable)`\n** `Arguments.toList()` — returns a mutable `List<@Nullable Object>`\n* `@EmptySource` now supports `Iterable`, `Iterator`, and `ListIterator`.\n* `@Deprecated` factory methods are now excluded in the\n xref:writing-tests/parameterized-classes-and-tests.adoc#argument-conversion-implicit-fallback[fallback String-to-Object]\n conversion algorithm.\n* Internal stack frames are now removed from `AssertionFailedError` stack traces.\n* New `trimStacktrace(Class)` and `retainStackTraceElements(int)` methods in\n `AssertionFailureBuilder` which allow user-defined assertions to trim their stack traces.\n* Generic inline value classes (such as `kotlin.Result`) can now be used as parameters\n in `@ParameterizedTest` methods when `kotlin-reflect` is on the classpath. Note,\n however, that primitive-wrapper inline value classes (such as `UInt` or custom value\n classes wrapping primitives) are not yet supported.\n* Kotlin-specific assertions now include a variant of `assertThrowsExactly` with reified\n generics.\n* The new `org.junit.jupiter.api.Constants` class provides constants for\n xref:running-tests/configuration-parameters.adoc[] specific to the Jupiter engine.\n* The `{EmptySource}` annotation now provides a `type` attribute that allows configuring\n the type of the empty argument explicitly. This is intended to be used in conjunction\n with an `{ArgumentConverter}` that supports the specified type.\n\n\n[[v6.1.0-RC1-junit-vintage]]\n=== JUnit Vintage\n\nNo changes.\n"
},
{
"path": "documentation/modules/ROOT/partials/release-notes/release-notes-6.1.0.adoc",
"content": "[[v6.1.0]]\n== 6.1.0\n\n*Date of Release:* ❓\n\n*Scope:* ❓\n\nFor a complete list of all _closed_ issues and pull requests for this release, consult the\nlink:{junit-framework-repo}+/milestone/119?closed=1+[6.1.0] milestone page in the JUnit\nrepository on GitHub.\n\n\n[[v6.1.0-junit-platform]]\n=== JUnit Platform\n\n[[v6.1.0-junit-platform-bug-fixes]]\n==== Bug Fixes\n\n* `AbstractTestDescriptor.getChildren()` now returns immutable set of children rather than a\n merely unmodifiable set.\n\n[[v6.1.0-junit-platform-deprecations-and-breaking-changes]]\n==== Deprecations and Breaking Changes\n\n* ❓\n\n[[v6.1.0-junit-platform-new-features-and-improvements]]\n==== New Features and Improvements\n\n* ❓\n\n\n[[v6.1.0-junit-jupiter]]\n=== JUnit Jupiter\n\n[[v6.1.0-junit-jupiter-bug-fixes]]\n==== Bug Fixes\n\n* ❓\n\n[[v6.1.0-junit-jupiter-deprecations-and-breaking-changes]]\n==== Deprecations and Breaking Changes\n\n* ❓\n\n[[v6.1.0-junit-jupiter-new-features-and-improvements]]\n==== New Features and Improvements\n\n* ❓\n\n\n[[v6.1.0-junit-vintage]]\n=== JUnit Vintage\n\n[[v6.1.0-junit-vintage-bug-fixes]]\n==== Bug Fixes\n\n* ❓\n\n[[v6.1.0-junit-vintage-deprecations-and-breaking-changes]]\n==== Deprecations and Breaking Changes\n\n* ❓\n\n[[v6.1.0-junit-vintage-new-features-and-improvements]]\n==== New Features and Improvements\n\n* ❓\n"
},
{
"path": "documentation/modules/ROOT/partials/release-notes/release-notes-TEMPLATE.adoc",
"content": "// TODO:\n//\n// 1) Make a copy of this template file, replacing TEMPLATE in the file name with the\n// current version (for example, 5.10.0-M1, 5.10.0-RC1, 5.10.0).\n// 2) Open the new file for editing.\n// 3) Replace all occurrences of VERSION with the current version (for example, 5.10.0-M1,\n// 5.10.0-RC1, 5.10.0). The same version must be used in the file name and within the\n// file.\n// 4) Replace MILESTONE_NUMBER with the appropriate milestone number. This is an integer\n// which you can determine via https://github.com/junit-team/junit-framework/milestones/.\n// If a GitHub milestone does not yet exist for the given VERSION, you will need to\n// create a new GitHub milestone or ask a member of the JUnit team to create it for you.\n// 5) 'include:' this new file in ../../pages/release-notes.adoc.\n// 6) Delete this entire comment block.\n//\n[[vVERSION]]\n== VERSION\n\n*Date of Release:* ❓\n\n*Scope:* ❓\n\nFor a complete list of all _closed_ issues and pull requests for this release, consult the\nlink:{junit-framework-repo}+/milestone/MILESTONE_NUMBER?closed=1+[VERSION] milestone page in the JUnit\nrepository on GitHub.\n\n\n[[vVERSION-junit-platform]]\n=== JUnit Platform\n\n[[vVERSION-junit-platform-bug-fixes]]\n==== Bug Fixes\n\n* ❓\n\n[[vVERSION-junit-platform-deprecations-and-breaking-changes]]\n==== Deprecations and Breaking Changes\n\n* ❓\n\n[[vVERSION-junit-platform-new-features-and-improvements]]\n==== New Features and Improvements\n\n* ❓\n\n\n[[vVERSION-junit-jupiter]]\n=== JUnit Jupiter\n\n[[vVERSION-junit-jupiter-bug-fixes]]\n==== Bug Fixes\n\n* ❓\n\n[[vVERSION-junit-jupiter-deprecations-and-breaking-changes]]\n==== Deprecations and Breaking Changes\n\n* ❓\n\n[[vVERSION-junit-jupiter-new-features-and-improvements]]\n==== New Features and Improvements\n\n* ❓\n\n\n[[vVERSION-junit-vintage]]\n=== JUnit Vintage\n\n[[vVERSION-junit-vintage-bug-fixes]]\n==== Bug Fixes\n\n* ❓\n\n[[vVERSION-junit-vintage-deprecations-and-breaking-changes]]\n==== Deprecations and Breaking Changes\n\n* ❓\n\n[[vVERSION-junit-vintage-new-features-and-improvements]]\n==== New Features and Improvements\n\n* ❓\n"
},
{
"path": "documentation/package.json",
"content": "{\n \"devDependencies\": {\n \"antora\": \"3.2.0-alpha.11\"\n },\n \"dependencies\": {\n \"@antora/collector-extension\": \"1.0.3\",\n \"@antora/lunr-extension\": \"1.0.0-alpha.13\",\n \"@asciidoctor/tabs\": \"^1.0.0-beta.6\",\n \"@springio/antora-extensions\": \"1.14.11\",\n \"@springio/antora-xref-extension\": \"^1.0.0-alpha.5\",\n \"highlight.js\": \"11.11.1\"\n }\n}\n"
},
{
"path": "documentation/src/javadoc/junit-overview.html",
"content": "\n\nThis document consists of four sections:
\n\n\n Platform \n The JUnit Platform serves as a foundation for launching testing frameworks on the JVM.\n It also defines the TestEngine API for developing a testing framework that runs on the\n platform. Furthermore, the platform provides a Console Launcher to launch the platform\n from the command line and the Suite Engine for running a custom test suite using one\n or more test engines on the platform\n \n Jupiter \n JUnit Jupiter is the combination of the programming model and extension model for\n writing JUnit tests and extensions. The Jupiter subproject provides a TestEngine\n for running Jupiter based tests on the platform.\n \n Vintage \n JUnit Vintage provides a TestEngine for running JUnit 3 and JUnit 4 based tests on the\n platform.\n \n Other Modules \n This section lists all modules that are not part of a dedicated section.\n \n \n\nAlready consulted the JUnit User Guide ?
\n\n\n"
},
{
"path": "documentation/src/javadoc/junit-stylesheet.css",
"content": "/*\n * CSS customizations for JUnit\n */\n\n@import url('https://assets.junit.org/fonts/index.css');\n\n:root {\n /* body, block and code fonts */\n --body-font-family: \"Inter Variable\", sans-serif;\n --block-font-family: \"Inter Variable\", sans-serif;\n --code-font-family: \"JetBrains Mono Variable\", monospace;\n /* Text colors for body and block elements */\n --body-text-color: #333;\n --block-text-color: #333;\n /* Colors for navigation bar and table captions */\n --navbar-background-color: #25a162;\n /* Background color for subnavigation and various headers */\n --subnav-background-color: #e8e8e8;\n --subnav-link-color: var(--link-color);\n /* Background and text colors for selected tabs and navigation items */\n --selected-background-color: #dc524a;\n --selected-text-color: #fff;\n --selected-link-color: #651410;\n /* Background colors for generated tables */\n --table-header-color: #eee;\n --even-row-color: #fff;\n --odd-row-color: #f6f6f6;\n /* Text color for page title */\n --title-color: #444;\n /* Text colors for links */\n --link-color: #dc524a;\n --link-color-active: #b62b23;\n /* Table of contents */\n --toc-background-color: #f8f8f8;\n --toc-hover-color: #eee;\n /* Snippet colors */\n --snippet-background-color: #ebecee;\n --snippet-text-color: var(--block-text-color);\n --snippet-highlight-color: #fcdbd9;\n /* Border colors for structural elements and user defined tables */\n --border-color: #eee;\n --table-border-color: #eee;\n /* Highlight color for active search tag target */\n --search-tag-highlight-color: #ffff00;\n /* Copy button colors and filters */\n --button-border-color: #b0b8c8;\n}\n\nh1, h2 {\n font-family: \"Blinker\", sans-serif;\n font-style: normal !important;\n font-weight: 600;\n}\n\ndl.notes > dt {\n font-size: var(--body-font-size);\n}\n\n@media screen and (min-width: 1024px) {\n .title {\n font-size: 2rem;\n }\n}\n\n.top-nav a:hover, .bottom-nav a:hover {\n text-decoration:underline;\n color:inherit;\n}\n\n.nav-bar-cell1-rev {\n background-color:#fff;\n color:#dc524a;\n border-radius: 6px;\n font-weight: bold;\n}\n\nhr {\n color: transparent;\n border-top: 1px solid var(--border-color);\n}\n\ndt {\n font-weight: bold;\n}\n\ntt,\ncode,\npre,\n.module-signature,\n.package-signature,\n.type-signature,\n.member-signature {\n font-variant-ligatures: none;\n}\n"
},
{
"path": "documentation/src/main/java/example/domain/Person.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.domain;\n\nimport java.time.LocalDate;\n\npublic final class Person {\n\n\tpublic enum Gender {\n\t\tF, M\n\t}\n\n\tprivate String firstName;\n\tprivate String lastName;\n\tprivate Gender gender;\n\tprivate LocalDate dateOfBirth;\n\n\tpublic Person(String firstName, String lastName) {\n\t\tthis.firstName = firstName;\n\t\tthis.lastName = lastName;\n\t}\n\n\tpublic Person(String firstName, String lastName, Gender gender, LocalDate dateOfBirth) {\n\t\tthis(firstName, lastName);\n\t\tthis.gender = gender;\n\t\tthis.dateOfBirth = dateOfBirth;\n\t}\n\n\tpublic String getFirstName() {\n\t\treturn firstName;\n\t}\n\n\tpublic String getLastName() {\n\t\treturn lastName;\n\t}\n\n\tpublic Gender getGender() {\n\t\treturn gender;\n\t}\n\n\tpublic LocalDate getDateOfBirth() {\n\t\treturn dateOfBirth;\n\t}\n\n\t@Override\n\tpublic int hashCode() {\n\t\tfinal int prime = 31;\n\t\tint result = 1;\n\t\tresult = prime * result + ((firstName == null) ? 0 : firstName.hashCode());\n\t\tresult = prime * result + ((lastName == null) ? 0 : lastName.hashCode());\n\t\treturn result;\n\t}\n\n\t@Override\n\tpublic boolean equals(Object obj) {\n\t\tif (this == obj) {\n\t\t\treturn true;\n\t\t}\n\t\tif (obj == null) {\n\t\t\treturn false;\n\t\t}\n\t\tif (getClass() != obj.getClass()) {\n\t\t\treturn false;\n\t\t}\n\t\tPerson other = (Person) obj;\n\t\tif (firstName == null) {\n\t\t\tif (other.firstName != null) {\n\t\t\t\treturn false;\n\t\t\t}\n\t\t}\n\t\telse if (!firstName.equals(other.firstName)) {\n\t\t\treturn false;\n\t\t}\n\t\tif (lastName == null) {\n\t\t\tif (other.lastName != null) {\n\t\t\t\treturn false;\n\t\t\t}\n\t\t}\n\t\telse if (!lastName.equals(other.lastName)) {\n\t\t\treturn false;\n\t\t}\n\t\treturn true;\n\t}\n\n\t@Override\n\tpublic String toString() {\n\t\treturn \"Person [firstName=\" + firstName + \", lastName=\" + lastName + \"]\";\n\t}\n\n}\n"
},
{
"path": "documentation/src/main/java/example/domain/package-info.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\n/**\n * Demo domain model.\n */\n\npackage example.domain;\n"
},
{
"path": "documentation/src/main/java/example/registration/WebClient.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.registration;\n\npublic class WebClient implements AutoCloseable {\n\n\tpublic WebResponse get(String string) {\n\t\treturn new WebResponse();\n\t}\n\n\t@Override\n\tpublic void close() {\n\t\t/* no-op for demo */\n\t}\n\n}\n"
},
{
"path": "documentation/src/main/java/example/registration/WebResponse.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.registration;\n\npublic class WebResponse {\n\n\tpublic int getResponseStatus() {\n\t\treturn 200;\n\t}\n\n}\n"
},
{
"path": "documentation/src/main/java/example/registration/WebServerExtension.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.registration;\n\nimport org.junit.jupiter.api.extension.BeforeAllCallback;\nimport org.junit.jupiter.api.extension.ExtensionContext;\n\npublic class WebServerExtension implements BeforeAllCallback {\n\n\t@Override\n\tpublic void beforeAll(ExtensionContext context) {\n\t\t/* no-op for demo */\n\t}\n\n\tpublic String getServerUrl() {\n\t\treturn \"https://example.org:8181\";\n\t}\n\n\tpublic static Builder builder() {\n\t\treturn new Builder();\n\t}\n\n\tpublic static class Builder {\n\n\t\tpublic Builder enableSecurity(boolean b) {\n\t\t\treturn this;\n\t\t}\n\n\t\tpublic WebServerExtension build() {\n\t\t\treturn new WebServerExtension();\n\t\t}\n\n\t}\n\n}\n"
},
{
"path": "documentation/src/main/java/example/registration/package-info.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\n/**\n * Demo code for a WebServer extension.\n */\n\npackage example.registration;\n"
},
{
"path": "documentation/src/main/java/example/util/Calculator.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.util;\n\npublic class Calculator {\n\n\tpublic int add(int a, int b) {\n\t\treturn a + b;\n\t}\n\n\tpublic int subtract(int a, int b) {\n\t\treturn a - b;\n\t}\n\n\tpublic int multiply(int a, int b) {\n\t\treturn a * b;\n\t}\n\n\tpublic int divide(int a, int b) {\n\t\treturn a / b;\n\t}\n\n}\n"
},
{
"path": "documentation/src/main/java/example/util/ListWriter.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.util;\n\nimport java.io.IOException;\nimport java.nio.file.Files;\nimport java.nio.file.Path;\nimport java.util.List;\n\npublic class ListWriter {\n\n\tprivate final Path file;\n\n\tpublic ListWriter(Path file) {\n\t\tthis.file = file;\n\t}\n\n\tpublic void write(String... items) throws IOException {\n\t\tFiles.write(file, List.of(String.join(\",\", items)));\n\t}\n\n}\n"
},
{
"path": "documentation/src/main/java/example/util/StringUtils.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.util;\n\nimport static java.util.Objects.requireNonNull;\n\nimport org.jspecify.annotations.Nullable;\n\npublic class StringUtils {\n\n\tpublic static boolean isPalindrome(@Nullable String candidate) {\n\t\tint length = requireNonNull(candidate).length();\n\t\tfor (int i = 0; i < length / 2; i++) {\n\t\t\tif (candidate.charAt(i) != candidate.charAt(length - (i + 1))) {\n\t\t\t\treturn false;\n\t\t\t}\n\t\t}\n\t\treturn true;\n\t}\n\n\tprivate StringUtils() {\n\t}\n\n}\n"
},
{
"path": "documentation/src/main/java/example/util/package-info.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\n/**\n * Demo utilities.\n */\n\npackage example.util;\n"
},
{
"path": "documentation/src/plantuml/component-diagram.puml",
"content": "@startuml\n\nskinparam {\n defaultFontName sans-serif\n}\n\npackage org.junit.jupiter {\n [junit-jupiter] as jupiter\n [junit-jupiter-api] as jupiter_api\n [junit-jupiter-engine] as jupiter_engine\n [junit-jupiter-params] as jupiter_params\n [junit-jupiter-migrationsupport] as jupiter_migration_support\n}\n\npackage org.junit.vintage {\n [junit-vintage-engine] as vintage_engine\n}\n\npackage org.junit.platform {\n [junit-platform-commons] as commons\n [junit-platform-console] as console\n [junit-platform-engine] as engine\n [junit-platform-launcher] as launcher\n [junit-platform-reporting] as reporting\n [junit-platform-suite] as suite\n [junit-platform-suite-api] as suite_api\n [junit-platform-suite-engine] as suite_engine\n [junit-platform-testkit] as testkit\n}\n\npackage \"JUnit 4\" {\n [junit:junit] as junit4\n}\n\npackage org.opentest4j {\n [opentest4j]\n}\n\npackage org.opentest4j.reporting {\n [open-test-reporting-tooling-spi] as otr_tooling_spi\n}\n\npackage org.apiguardian {\n [apiguardian-api] as apiguardian\n note bottom of apiguardian #white\n All artifacts except\n opentest4j and junit:junit\n have a dependency on this\n artifact. The edges have\n been omitted from this\n diagram for the sake of\n readability.\n endnote\n}\n\njupiter ..> jupiter_api\njupiter ..> jupiter_params\njupiter ..> jupiter_engine\n\njupiter_api ....> opentest4j\njupiter_api ...> commons\n\njupiter_engine ...> engine\njupiter_engine ..> jupiter_api\n\njupiter_params ..> jupiter_api\njupiter_migration_support ..> jupiter_api\njupiter_migration_support ...> junit4\n\nconsole ..> launcher\nconsole ..> reporting\n\nlauncher ..> engine\n\nengine ....> opentest4j\nengine ..> commons\n\nreporting ..> launcher\nreporting ......> otr_tooling_spi\n\nsuite ..> suite_api\nsuite ..> suite_engine\n\nsuite_engine ..> launcher\nsuite_engine ..> suite_api\n\ntestkit ....> opentest4j\ntestkit ..> launcher\n\nvintage_engine ...> engine\nvintage_engine ..> junit4\n\n@enduml\n"
},
{
"path": "documentation/src/plantuml/junit-platform-suite-engine-diagram.puml",
"content": "@startuml\nobject \"IDEs\"\nobject \"Build Tools\"\nobject \"Console Launcher\"\n\nobject \"JUnit Platform\"\nobject \"Suite Test Engine\"\n\nobject \"@Suite annotated class A\"\nobject \"@Suite annotated class B\"\nobject \"JUnit Platform (A)\"\nobject \"JUnit Platform (B)\"\nobject \"Jupiter Test Engine (A)\"\nobject \"Jupiter Test Engine (B)\"\nobject \"Tests in package A\"\nobject \"Tests in package B\"\n\n\"IDEs\" --> \"JUnit Platform\"\n\"Build Tools\" --> \"JUnit Platform\"\n\"Console Launcher\" --> \"JUnit Platform\" : requests discovery and execution\n\"JUnit Platform\" --> \"Suite Test Engine\": forwards request\n\n\"Suite Test Engine\" --> \"@Suite annotated class A\"\n\"@Suite annotated class A\" --> \"JUnit Platform (A)\" \n\"JUnit Platform (A)\" --> \"Jupiter Test Engine (A)\"\n\"Jupiter Test Engine (A)\" --> \"Tests in package A\"\n\n\"Suite Test Engine\" --> \"@Suite annotated class B\" : discovers and executes\n\"@Suite annotated class B\" --> \"JUnit Platform (B)\" : requests discovery and execution\n\"JUnit Platform (B)\" --> \"Jupiter Test Engine (B)\" : forwards request\n\"Jupiter Test Engine (B)\" --> \"Tests in package B\" : discovers and executes\n@enduml\n"
},
{
"path": "documentation/src/plantuml/junit-platform-suite-engine-duplicate-test-execution-diagram.puml",
"content": "@startuml\nobject \"IDEs\"\nobject \"Build Tools\"\nobject \"Console Launcher\"\nobject \"JUnit Platform\"\ntogether {\n object \"Suite Test Engine\"\n object \"Jupiter Test Engine\"\n}\nobject \"@Suite annotated class\"\nobject \"JUnit Platform (@Suite)\"\nobject \"Jupiter Test Engine (@Suite)\"\ntogether {\n object \"Example Test A\"\n object \"Example Test A (@Suite)\"\n}\n\n\"IDEs\" --> \"JUnit Platform\"\n\"Build Tools\" --> \"JUnit Platform\"\n\"Console Launcher\" --> \"JUnit Platform\" : requests discovery and execution\n\n\"JUnit Platform\" --> \"Suite Test Engine\"\n\"Suite Test Engine\" --> \"@Suite annotated class\" : discovers and executes\n\"@Suite annotated class\" --> \"JUnit Platform (@Suite)\" : requests discovery and execution\n\"JUnit Platform (@Suite)\" --> \"Jupiter Test Engine (@Suite)\" : forwards request\n\"Jupiter Test Engine (@Suite)\" --> \"Example Test A (@Suite)\" : discovers and executes\n\n\"JUnit Platform\" --> \"Jupiter Test Engine\": forwards request\n\"Jupiter Test Engine\" --> \"Example Test A\" #line:red;line.bold;text:red : also discovers and executes!\n@enduml\n"
},
{
"path": "documentation/src/plantuml/launcher-api-diagram.puml",
"content": "@startuml\nobject \"IDEs\"\nobject \"Build Tools\"\nobject \"Console Launcher\"\nobject \"JUnit Platform\"\nobject \"Jupiter Test Engine\"\nobject \"Cucumber Test Engine\"\nobject \"Spock Test Engine\"\nobject \"Test Classes\"\nobject \"Feature Files\"\nobject \"Specifications\"\n\n\"IDEs\" --> \"JUnit Platform\"\n\"Build Tools\" --> \"JUnit Platform\"\n\"Console Launcher\" --> \"JUnit Platform\" : requests discovery and execution\n\"JUnit Platform\" --> \"Jupiter Test Engine\"\n\"Jupiter Test Engine\" --> \"Test Classes\"\n\n\"JUnit Platform\" --> \"Cucumber Test Engine\"\n\"Cucumber Test Engine\" --> \"Feature Files\"\n\n\"JUnit Platform\" --> \"Spock Test Engine\": forwards request\n\"Spock Test Engine\" --> \"Specifications\" : discovers and executes\n@enduml\n"
},
{
"path": "documentation/src/test/java/example/AssertJAssertionsDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\n// tag::user_guide[]\nimport static org.assertj.core.api.Assertions.assertThat;\n\nimport example.util.Calculator;\n\nimport org.junit.jupiter.api.Test;\n\nclass AssertJAssertionsDemo {\n\n\tprivate final Calculator calculator = new Calculator();\n\n\t@Test\n\tvoid assertWithAssertJ() {\n\t\tassertThat(calculator.subtract(4, 1)).isEqualTo(3);\n\t}\n\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/AssertionsDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\n// @formatter:off\n// tag::user_guide[]\nimport static java.time.Duration.ofMillis;\nimport static java.time.Duration.ofMinutes;\nimport static org.junit.jupiter.api.Assertions.assertAll;\nimport static org.junit.jupiter.api.Assertions.assertEquals;\nimport static org.junit.jupiter.api.Assertions.assertNotNull;\nimport static org.junit.jupiter.api.Assertions.assertThrows;\nimport static org.junit.jupiter.api.Assertions.assertTimeout;\nimport static org.junit.jupiter.api.Assertions.assertTimeoutPreemptively;\nimport static org.junit.jupiter.api.Assertions.assertTrue;\n\nimport java.util.concurrent.CountDownLatch;\n\nimport example.domain.Person;\nimport example.util.Calculator;\n\nimport org.junit.jupiter.api.Tag;\nimport org.junit.jupiter.api.Test;\n\nclass AssertionsDemo {\n\n\tprivate final Calculator calculator = new Calculator();\n\n\tprivate final Person person = new Person(\"Jane\", \"Doe\");\n\n\t@Test\n\tvoid standardAssertions() {\n\t\tassertEquals(2, calculator.add(1, 1));\n\t\tassertEquals(4, calculator.multiply(2, 2),\n\t\t\t\t\"The optional failure message is now the last parameter\");\n\n\t\t// Lazily evaluates generateFailureMessage('a','b').\n\t\tassertTrue('a' < 'b', () -> generateFailureMessage('a','b'));\n\t}\n\n\t@Test\n\tvoid groupedAssertions() {\n\t\t// In a grouped assertion all assertions are executed, and all\n\t\t// failures will be reported together.\n\t\tassertAll(\"person\",\n\t\t\t() -> assertEquals(\"Jane\", person.getFirstName()),\n\t\t\t() -> assertEquals(\"Doe\", person.getLastName())\n\t\t);\n\t}\n\n\t@Test\n\tvoid dependentAssertions() {\n\t\t// Within a code block, if an assertion fails the\n\t\t// subsequent code in the same block will be skipped.\n\t\tassertAll(\"properties\",\n\t\t\t() -> {\n\t\t\t\tString firstName = person.getFirstName();\n\t\t\t\tassertNotNull(firstName);\n\n\t\t\t\t// Executed only if the previous assertion is valid.\n\t\t\t\tassertAll(\"first name\",\n\t\t\t\t\t() -> assertTrue(firstName.startsWith(\"J\")),\n\t\t\t\t\t() -> assertTrue(firstName.endsWith(\"e\"))\n\t\t\t\t);\n\t\t\t},\n\t\t\t() -> {\n\t\t\t\t// Grouped assertion, so processed independently\n\t\t\t\t// of results of first name assertions.\n\t\t\t\tString lastName = person.getLastName();\n\t\t\t\tassertNotNull(lastName);\n\n\t\t\t\t// Executed only if the previous assertion is valid.\n\t\t\t\tassertAll(\"last name\",\n\t\t\t\t\t() -> assertTrue(lastName.startsWith(\"D\")),\n\t\t\t\t\t() -> assertTrue(lastName.endsWith(\"e\"))\n\t\t\t\t);\n\t\t\t}\n\t\t);\n\t}\n\n\t// end::user_guide[]\n\t@extensions.DisabledOnOpenJ9\n\t// tag::user_guide[]\n\t@Test\n\tvoid exceptionTesting() {\n\t\tException exception = assertThrows(ArithmeticException.class, () ->\n\t\t\tcalculator.divide(1, 0));\n\t\tassertEquals(\"/ by zero\", exception.getMessage());\n\t}\n\n\t// end::user_guide[]\n\t@Tag(\"timeout\")\n\t// tag::user_guide[]\n\t@Test\n\tvoid timeoutNotExceeded() {\n\t\t// The following assertion succeeds.\n\t\tassertTimeout(ofMinutes(2), () -> {\n\t\t\t// Perform task that takes less than 2 minutes.\n\t\t});\n\t}\n\n\t// end::user_guide[]\n\t@Tag(\"timeout\")\n\t// tag::user_guide[]\n\t@Test\n\tvoid timeoutNotExceededWithResult() {\n\t\t// The following assertion succeeds, and returns the supplied object.\n\t\tString actualResult = assertTimeout(ofMinutes(2), () -> {\n\t\t\treturn \"a result\";\n\t\t});\n\t\tassertEquals(\"a result\", actualResult);\n\t}\n\n\t// end::user_guide[]\n\t@Tag(\"timeout\")\n\t// tag::user_guide[]\n\t@Test\n\tvoid timeoutNotExceededWithMethod() {\n\t\t// The following assertion invokes a method reference and returns an object.\n\t\tString actualGreeting = assertTimeout(ofMinutes(2), AssertionsDemo::greeting);\n\t\tassertEquals(\"Hello, World!\", actualGreeting);\n\t}\n\n\t// end::user_guide[]\n\t@Tag(\"timeout\")\n\t@extensions.ExpectToFail\n\t// tag::user_guide[]\n\t@Test\n\tvoid timeoutExceeded() {\n\t\t// The following assertion fails with an error message similar to:\n\t\t// execution exceeded timeout of 10 ms by 91 ms\n\t\tassertTimeout(ofMillis(10), () -> {\n\t\t\t// Simulate task that takes more than 10 ms.\n\t\t\tThread.sleep(100);\n\t\t});\n\t}\n\n\t// end::user_guide[]\n\t@Tag(\"timeout\")\n\t@extensions.ExpectToFail\n\t// tag::user_guide[]\n\t@Test\n\tvoid timeoutExceededWithPreemptiveTermination() {\n\t\t// The following assertion fails with an error message similar to:\n\t\t// execution timed out after 10 ms\n\t\tassertTimeoutPreemptively(ofMillis(10), () -> {\n\t\t\t// Simulate task that takes more than 10 ms.\n\t\t\tnew CountDownLatch(1).await();\n\t\t});\n\t}\n\n\tprivate static String greeting() {\n\t\treturn \"Hello, World!\";\n\t}\n\n\tprivate static String generateFailureMessage(char a, char b) {\n\t\treturn \"Assertion messages can be lazily evaluated -- \"\n\t\t\t\t+ \"to avoid constructing complex messages unnecessarily.\" + (a < b);\n\t}\n}\n// end::user_guide[]\n// @formatter:on\n"
},
{
"path": "documentation/src/test/java/example/AssumptionsDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\n// @formatter:off\n// tag::user_guide[]\n\nimport static org.junit.jupiter.api.Assertions.assertEquals;\nimport static org.junit.jupiter.api.Assumptions.assumeTrue;\nimport static org.junit.jupiter.api.Assumptions.assumingThat;\n\nimport example.util.Calculator;\n\nimport org.junit.jupiter.api.Test;\n\nclass AssumptionsDemo {\n\n\tprivate final Calculator calculator = new Calculator();\n\n\t@Test\n\tvoid testOnlyOnCiServer() {\n\t\tassumeTrue(\"CI\".equals(System.getenv(\"ENV\")));\n\t\t// remainder of test\n\t}\n\n\t@Test\n\tvoid testOnlyOnDeveloperWorkstation() {\n\t\tassumeTrue(\"DEV\".equals(System.getenv(\"ENV\")),\n\t\t\t() -> \"Aborting test: not on developer workstation\");\n\t\t// remainder of test\n\t}\n\n\t@Test\n\tvoid testInAllEnvironments() {\n\t\tassumingThat(\"CI\".equals(System.getenv(\"ENV\")),\n\t\t\t() -> {\n\t\t\t\t// perform these assertions only on the CI server\n\t\t\t\tassertEquals(2, calculator.divide(4, 2));\n\t\t\t});\n\n\t\t// perform these assertions in all environments\n\t\tassertEquals(42, calculator.multiply(6, 7));\n\t}\n\n}\n// end::user_guide[]\n// @formatter:on\n"
},
{
"path": "documentation/src/test/java/example/AutoCloseDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\nimport static org.junit.jupiter.api.Assertions.assertEquals;\n\nimport example.registration.WebClient;\n\nimport org.junit.jupiter.api.AutoClose;\nimport org.junit.jupiter.api.Test;\n\n// tag::user_guide_example[]\nclass AutoCloseDemo {\n\n\t@AutoClose // <1>\n\tWebClient webClient = new WebClient(); // <2>\n\n\tString serverUrl = // specify server URL ...\n\t\t// end::user_guide_example[]\n\t\t\"https://localhost\";\n\t// tag::user_guide_example[]\n\n\t@Test\n\tvoid getProductList() {\n\t\t// Use WebClient to connect to web server and verify response\n\t\tassertEquals(200, webClient.get(serverUrl + \"/products\").getResponseStatus());\n\t}\n\n}\n// end::user_guide_example[]\n"
},
{
"path": "documentation/src/test/java/example/BeforeAndAfterSuiteDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\nimport org.junit.platform.suite.api.AfterSuite;\nimport org.junit.platform.suite.api.BeforeSuite;\nimport org.junit.platform.suite.api.SelectPackages;\nimport org.junit.platform.suite.api.Suite;\n\n//tag::user_guide[]\n@Suite\n@SelectPackages(\"example\")\nclass BeforeAndAfterSuiteDemo {\n\n\t@BeforeSuite\n\tstatic void beforeSuite() {\n\t\t// executes before the test suite\n\t}\n\n\t@AfterSuite\n\tstatic void afterSuite() {\n\t\t// executes after the test suite\n\t}\n\n}\n//end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/ClassTemplateDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\nimport static org.junit.jupiter.api.Assertions.assertNotNull;\nimport static org.junit.jupiter.api.Assertions.assertTrue;\n\nimport java.util.List;\nimport java.util.stream.Stream;\n\nimport org.jspecify.annotations.Nullable;\nimport org.junit.jupiter.api.ClassTemplate;\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.extension.ClassTemplateInvocationContext;\nimport org.junit.jupiter.api.extension.ClassTemplateInvocationContextProvider;\nimport org.junit.jupiter.api.extension.ExtendWith;\nimport org.junit.jupiter.api.extension.Extension;\nimport org.junit.jupiter.api.extension.ExtensionContext;\nimport org.junit.jupiter.api.extension.TestInstancePostProcessor;\n\n// tag::user_guide[]\n@ClassTemplate\n@ExtendWith(ClassTemplateDemo.MyClassTemplateInvocationContextProvider.class)\nclass ClassTemplateDemo {\n\n\tstatic final List WELL_KNOWN_FRUITS\n\t// tag::custom_line_break[]\n\t\t= List.of(\"apple\", \"banana\", \"lemon\");\n\n\t//end::user_guide[]\n\t@Nullable\n\t//tag::user_guide[]\n\tprivate String fruit;\n\n\t@Test\n\tvoid notNull() {\n\t\tassertNotNull(fruit);\n\t}\n\n\t@Test\n\tvoid wellKnown() {\n\t\tassertTrue(WELL_KNOWN_FRUITS.contains(fruit));\n\t}\n\n\t// end::user_guide[]\n\tstatic\n\t// tag::user_guide[]\n\tpublic class MyClassTemplateInvocationContextProvider\n\t\t\t// tag::custom_line_break[]\n\t\t\timplements ClassTemplateInvocationContextProvider {\n\n\t\t@Override\n\t\tpublic boolean supportsClassTemplate(ExtensionContext context) {\n\t\t\treturn true;\n\t\t}\n\n\t\t@Override\n\t\tpublic Stream\n\t\t\t\t// tag::custom_line_break[]\n\t\t\t\tprovideClassTemplateInvocationContexts(ExtensionContext context) {\n\n\t\t\treturn Stream.of(invocationContext(\"apple\"), invocationContext(\"banana\"));\n\t\t}\n\n\t\tprivate ClassTemplateInvocationContext invocationContext(String parameter) {\n\t\t\treturn new ClassTemplateInvocationContext() {\n\t\t\t\t@Override\n\t\t\t\tpublic String getDisplayName(int invocationIndex) {\n\t\t\t\t\treturn parameter;\n\t\t\t\t}\n\n\t\t\t\t// end::user_guide[]\n\t\t\t\t@SuppressWarnings(\"Convert2Lambda\")\n\t\t\t\t// tag::user_guide[]\n\t\t\t\t@Override\n\t\t\t\tpublic List getAdditionalExtensions() {\n\t\t\t\t\treturn List.of(new TestInstancePostProcessor() {\n\t\t\t\t\t\t@Override\n\t\t\t\t\t\tpublic void postProcessTestInstance(\n\t\t\t\t\t\t\t\t// tag::custom_line_break[]\n\t\t\t\t\t\t\t\tObject testInstance, ExtensionContext context) {\n\t\t\t\t\t\t\t((ClassTemplateDemo) testInstance).fruit = parameter;\n\t\t\t\t\t\t}\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t};\n\t\t}\n\t}\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/ConditionalTestExecutionDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\nimport static org.junit.jupiter.api.condition.JRE.JAVA_17;\nimport static org.junit.jupiter.api.condition.JRE.JAVA_18;\nimport static org.junit.jupiter.api.condition.JRE.JAVA_19;\nimport static org.junit.jupiter.api.condition.JRE.JAVA_21;\nimport static org.junit.jupiter.api.condition.JRE.JAVA_25;\nimport static org.junit.jupiter.api.condition.OS.LINUX;\nimport static org.junit.jupiter.api.condition.OS.MAC;\nimport static org.junit.jupiter.api.condition.OS.WINDOWS;\n\nimport java.lang.annotation.ElementType;\nimport java.lang.annotation.Retention;\nimport java.lang.annotation.RetentionPolicy;\nimport java.lang.annotation.Target;\n\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.condition.DisabledForJreRange;\nimport org.junit.jupiter.api.condition.DisabledIf;\nimport org.junit.jupiter.api.condition.DisabledIfEnvironmentVariable;\nimport org.junit.jupiter.api.condition.DisabledIfSystemProperty;\nimport org.junit.jupiter.api.condition.DisabledInNativeImage;\nimport org.junit.jupiter.api.condition.DisabledOnJre;\nimport org.junit.jupiter.api.condition.DisabledOnOs;\nimport org.junit.jupiter.api.condition.EnabledForJreRange;\nimport org.junit.jupiter.api.condition.EnabledIf;\nimport org.junit.jupiter.api.condition.EnabledIfEnvironmentVariable;\nimport org.junit.jupiter.api.condition.EnabledIfSystemProperty;\nimport org.junit.jupiter.api.condition.EnabledInNativeImage;\nimport org.junit.jupiter.api.condition.EnabledOnJre;\nimport org.junit.jupiter.api.condition.EnabledOnOs;\n\nclass ConditionalTestExecutionDemo {\n\n\t// tag::user_guide_os[]\n\t@Test\n\t@EnabledOnOs(MAC)\n\tvoid onlyOnMacOs() {\n\t\t// ...\n\t}\n\n\t@TestOnMac\n\tvoid testOnMac() {\n\t\t// ...\n\t}\n\n\t@Test\n\t@EnabledOnOs({ LINUX, MAC })\n\tvoid onLinuxOrMac() {\n\t\t// ...\n\t}\n\n\t@Test\n\t@DisabledOnOs(WINDOWS)\n\tvoid notOnWindows() {\n\t\t// ...\n\t}\n\n\t@Target(ElementType.METHOD)\n\t@Retention(RetentionPolicy.RUNTIME)\n\t@Test\n\t@EnabledOnOs(MAC)\n\t@interface TestOnMac {\n\t}\n\t// end::user_guide_os[]\n\n\t// tag::user_guide_architecture[]\n\t@Test\n\t@EnabledOnOs(architectures = \"aarch64\")\n\tvoid onAarch64() {\n\t\t// ...\n\t}\n\n\t@Test\n\t@DisabledOnOs(architectures = \"x86_64\")\n\tvoid notOnX86_64() {\n\t\t// ...\n\t}\n\n\t@Test\n\t@EnabledOnOs(value = MAC, architectures = \"aarch64\")\n\tvoid onNewMacs() {\n\t\t// ...\n\t}\n\n\t@Test\n\t@DisabledOnOs(value = MAC, architectures = \"aarch64\")\n\tvoid notOnNewMacs() {\n\t\t// ...\n\t}\n\t// end::user_guide_architecture[]\n\n\t// tag::user_guide_jre[]\n\t@Test\n\t@EnabledOnJre(JAVA_17)\n\tvoid onlyOnJava17() {\n\t\t// ...\n\t}\n\n\t@Test\n\t@EnabledOnJre({ JAVA_17, JAVA_21 })\n\tvoid onJava17And21() {\n\t\t// ...\n\t}\n\n\t@Test\n\t@EnabledForJreRange(min = JAVA_21, max = JAVA_25)\n\tvoid fromJava21To25() {\n\t\t// ...\n\t}\n\n\t@Test\n\t@EnabledForJreRange(min = JAVA_21)\n\tvoid onJava21ndHigher() {\n\t\t// ...\n\t}\n\n\t@Test\n\t@EnabledForJreRange(max = JAVA_18)\n\tvoid fromJava17To18() {\n\t\t// ...\n\t}\n\n\t@Test\n\t@DisabledOnJre(JAVA_19)\n\tvoid notOnJava19() {\n\t\t// ...\n\t}\n\n\t@Test\n\t@DisabledForJreRange(min = JAVA_17, max = JAVA_17)\n\tvoid notFromJava17To19() {\n\t\t// ...\n\t}\n\n\t@Test\n\t@DisabledForJreRange(min = JAVA_19)\n\tvoid notOnJava19AndHigher() {\n\t\t// ...\n\t}\n\n\t@Test\n\t@DisabledForJreRange(max = JAVA_18)\n\tvoid notFromJava17To18() {\n\t\t// ...\n\t}\n\t// end::user_guide_jre[]\n\n\t// tag::user_guide_jre_arbitrary_versions[]\n\t@Test\n\t@EnabledOnJre(versions = 26)\n\tvoid onlyOnJava26() {\n\t\t// ...\n\t}\n\n\t@Test\n\t@EnabledOnJre(versions = { 25, 26 })\n\t// Can also be expressed as follows.\n\t// @EnabledOnJre(value = JAVA_25, versions = 26)\n\tvoid onJava25And26() {\n\t\t// ...\n\t}\n\n\t@Test\n\t@EnabledForJreRange(minVersion = 26)\n\tvoid onJava26AndHigher() {\n\t\t// ...\n\t}\n\n\t@Test\n\t@EnabledForJreRange(minVersion = 25, maxVersion = 27)\n\t// Can also be expressed as follows.\n\t// @EnabledForJreRange(min = JAVA_25, maxVersion = 27)\n\tvoid fromJava25To27() {\n\t\t// ...\n\t}\n\n\t@Test\n\t@DisabledOnJre(versions = 26)\n\tvoid notOnJava26() {\n\t\t// ...\n\t}\n\n\t@Test\n\t@DisabledOnJre(versions = { 25, 26 })\n\t// Can also be expressed as follows.\n\t// @DisabledOnJre(value = JAVA_25, versions = 26)\n\tvoid notOnJava25And26() {\n\t\t// ...\n\t}\n\n\t@Test\n\t@DisabledForJreRange(minVersion = 26)\n\tvoid notOnJava26AndHigher() {\n\t\t// ...\n\t}\n\n\t@Test\n\t@DisabledForJreRange(minVersion = 25, maxVersion = 27)\n\t// Can also be expressed as follows.\n\t// @DisabledForJreRange(min = JAVA_25, maxVersion = 27)\n\tvoid notFromJava25To27() {\n\t\t// ...\n\t}\n\t// end::user_guide_jre_arbitrary_versions[]\n\n\t// tag::user_guide_native[]\n\t@Test\n\t@EnabledInNativeImage\n\tvoid onlyWithinNativeImage() {\n\t\t// ...\n\t}\n\n\t@Test\n\t@DisabledInNativeImage\n\tvoid neverWithinNativeImage() {\n\t\t// ...\n\t}\n\t// end::user_guide_native[]\n\n\t// tag::user_guide_system_property[]\n\t@Test\n\t@EnabledIfSystemProperty(named = \"os.arch\", matches = \".*64.*\")\n\tvoid onlyOn64BitArchitectures() {\n\t\t// ...\n\t}\n\n\t@Test\n\t@DisabledIfSystemProperty(named = \"ci-server\", matches = \"true\")\n\tvoid notOnCiServer() {\n\t\t// ...\n\t}\n\t// end::user_guide_system_property[]\n\n\t// tag::user_guide_environment_variable[]\n\t@Test\n\t@EnabledIfEnvironmentVariable(named = \"ENV\", matches = \"staging-server\")\n\tvoid onlyOnStagingServer() {\n\t\t// ...\n\t}\n\n\t@Test\n\t@DisabledIfEnvironmentVariable(named = \"ENV\", matches = \".*development.*\")\n\tvoid notOnDeveloperWorkstation() {\n\t\t// ...\n\t}\n\t// end::user_guide_environment_variable[]\n\n\t// tag::user_guide_custom[]\n\t@Test\n\t@EnabledIf(\"customCondition\")\n\tvoid enabled() {\n\t\t// ...\n\t}\n\n\t@Test\n\t@DisabledIf(\"customCondition\")\n\tvoid disabled() {\n\t\t// ...\n\t}\n\n\tboolean customCondition() {\n\t\treturn true;\n\t}\n\t// end::user_guide_custom[]\n\n}\n"
},
{
"path": "documentation/src/test/java/example/CustomLauncherInterceptor.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\n// tag::user_guide[]\n\nimport java.io.IOException;\nimport java.io.UncheckedIOException;\nimport java.net.URI;\nimport java.net.URL;\nimport java.net.URLClassLoader;\n\nimport org.junit.platform.launcher.LauncherInterceptor;\n\npublic class CustomLauncherInterceptor implements LauncherInterceptor {\n\n\tprivate final URLClassLoader customClassLoader;\n\n\tpublic CustomLauncherInterceptor() throws Exception {\n\t\tClassLoader parent = Thread.currentThread().getContextClassLoader();\n\t\tcustomClassLoader = new URLClassLoader(new URL[] { URI.create(\"some.jar\").toURL() }, parent);\n\t}\n\n\t@Override\n\tpublic T intercept(Invocation invocation) {\n\t\tThread currentThread = Thread.currentThread();\n\t\tClassLoader originalClassLoader = currentThread.getContextClassLoader();\n\t\tcurrentThread.setContextClassLoader(customClassLoader);\n\t\ttry {\n\t\t\treturn invocation.proceed();\n\t\t}\n\t\tfinally {\n\t\t\tcurrentThread.setContextClassLoader(originalClassLoader);\n\t\t}\n\t}\n\n\t@Override\n\tpublic void close() {\n\t\ttry {\n\t\t\tcustomClassLoader.close();\n\t\t}\n\t\tcatch (IOException e) {\n\t\t\tthrow new UncheckedIOException(\"Failed to close custom class loader\", e);\n\t\t}\n\t}\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/CustomTestEngine.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\nimport org.junit.platform.engine.EngineDiscoveryRequest;\nimport org.junit.platform.engine.ExecutionRequest;\nimport org.junit.platform.engine.TestDescriptor;\nimport org.junit.platform.engine.TestEngine;\nimport org.junit.platform.engine.UniqueId;\nimport org.junit.platform.engine.support.descriptor.EngineDescriptor;\n\n/**\n * This is a no-op {@link TestEngine} that is only\n * used to make examples compile.\n */\nclass CustomTestEngine implements TestEngine {\n\n\t@Override\n\tpublic String getId() {\n\t\treturn \"custom-test-engine\";\n\t}\n\n\t@Override\n\tpublic TestDescriptor discover(EngineDiscoveryRequest discoveryRequest, UniqueId uniqueId) {\n\t\treturn new EngineDescriptor(UniqueId.forEngine(getId()), \"Custom Test Engine\");\n\t}\n\n\t@Override\n\tpublic void execute(ExecutionRequest request) {\n\t}\n\n}\n"
},
{
"path": "documentation/src/test/java/example/DefaultLocaleTimezoneExtensionDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\nimport static org.assertj.core.api.Assertions.assertThat;\n\nimport java.time.ZoneOffset;\nimport java.util.Locale;\nimport java.util.TimeZone;\n\nimport org.junit.jupiter.api.Nested;\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.util.DefaultLocale;\nimport org.junit.jupiter.api.util.DefaultTimeZone;\nimport org.junit.jupiter.api.util.LocaleProvider;\nimport org.junit.jupiter.api.util.TimeZoneProvider;\n\npublic class DefaultLocaleTimezoneExtensionDemo {\n\n\t// tag::default_locale_language[]\n\t@Test\n\t@DefaultLocale(\"zh-Hant-TW\")\n\tvoid test_with_language() {\n\t\tassertThat(Locale.getDefault()).isEqualTo(Locale.forLanguageTag(\"zh-Hant-TW\"));\n\t}\n\t// end::default_locale_language[]\n\n\t// tag::default_locale_language_alternatives[]\n\t@Test\n\t@DefaultLocale(language = \"en\")\n\tvoid test_with_language_only() {\n\t\tassertThat(Locale.getDefault()).isEqualTo(new Locale.Builder().setLanguage(\"en\").build());\n\t}\n\n\t@Test\n\t@DefaultLocale(language = \"en\", country = \"EN\")\n\tvoid test_with_language_and_country() {\n\t\tassertThat(Locale.getDefault()).isEqualTo(new Locale.Builder().setLanguage(\"en\").setRegion(\"EN\").build());\n\t}\n\n\t@Test\n\t@DefaultLocale(language = \"ja\", country = \"JP\", variant = \"japanese\")\n\tvoid test_with_language_and_country_and_vairant() {\n\t\tassertThat(Locale.getDefault()).isEqualTo(\n\t\t\tnew Locale.Builder().setLanguage(\"ja\").setRegion(\"JP\").setVariant(\"japanese\").build());\n\t}\n\t// end::default_locale_language_alternatives[]\n\n\t@Nested\n\t// tag::default_locale_class_level[]\n\t@DefaultLocale(language = \"fr\")\n\tclass MyLocaleTests {\n\n\t\t@Test\n\t\tvoid test_with_class_level_configuration() {\n\t\t\tassertThat(Locale.getDefault()).isEqualTo(new Locale.Builder().setLanguage(\"fr\").build());\n\t\t}\n\n\t\t@Test\n\t\t@DefaultLocale(language = \"en\")\n\t\tvoid test_with_method_level_configuration() {\n\t\t\tassertThat(Locale.getDefault()).isEqualTo(new Locale.Builder().setLanguage(\"en\").build());\n\t\t}\n\n\t}\n\t// end::default_locale_class_level[]\n\n\t// tag::default_locale_with_provider[]\n\t@Test\n\t@DefaultLocale(localeProvider = EnglishProvider.class)\n\tvoid test_with_locale_provider() {\n\t\tassertThat(Locale.getDefault()).isEqualTo(new Locale.Builder().setLanguage(\"en\").build());\n\t}\n\n\tstatic class EnglishProvider implements LocaleProvider {\n\t\t@Override\n\t\tpublic Locale get() {\n\t\t\treturn Locale.ENGLISH;\n\t\t}\n\t}\n\t// end::default_locale_with_provider[]\n\n\t// tag::default_timezone_zone[]\n\t@Test\n\t@DefaultTimeZone(\"CET\")\n\tvoid test_with_short_zone_id() {\n\t\tassertThat(TimeZone.getDefault()).isEqualTo(TimeZone.getTimeZone(\"CET\"));\n\t}\n\n\t@Test\n\t@DefaultTimeZone(\"Africa/Juba\")\n\tvoid test_with_long_zone_id() {\n\t\tassertThat(TimeZone.getDefault()).isEqualTo(TimeZone.getTimeZone(\"Africa/Juba\"));\n\t}\n\t// end::default_timezone_zone[]\n\n\t@Nested\n\t// tag::default_timezone_class_level[]\n\t@DefaultTimeZone(\"CET\")\n\tclass MyTimeZoneTests {\n\n\t\t@Test\n\t\tvoid test_with_class_level_configuration() {\n\t\t\tassertThat(TimeZone.getDefault()).isEqualTo(TimeZone.getTimeZone(\"CET\"));\n\t\t}\n\n\t\t@Test\n\t\t@DefaultTimeZone(\"Africa/Juba\")\n\t\tvoid test_with_method_level_configuration() {\n\t\t\tassertThat(TimeZone.getDefault()).isEqualTo(TimeZone.getTimeZone(\"Africa/Juba\"));\n\t\t}\n\n\t}\n\t// end::default_timezone_class_level[]\n\n\t// tag::default_time_zone_with_provider[]\n\t@Test\n\t@DefaultTimeZone(timeZoneProvider = UtcTimeZoneProvider.class)\n\tvoid test_with_time_zone_provider() {\n\t\tassertThat(TimeZone.getDefault()).isEqualTo(TimeZone.getTimeZone(\"UTC\"));\n\t}\n\n\tstatic class UtcTimeZoneProvider implements TimeZoneProvider {\n\t\t@Override\n\t\tpublic TimeZone get() {\n\t\t\treturn TimeZone.getTimeZone(ZoneOffset.UTC);\n\t\t}\n\t}\n\t// end::default_time_zone_with_provider[]\n\n}\n"
},
{
"path": "documentation/src/test/java/example/DisabledClassDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\n// tag::user_guide[]\nimport org.junit.jupiter.api.Disabled;\nimport org.junit.jupiter.api.Test;\n\n@Disabled(\"Disabled until bug #99 has been fixed\")\nclass DisabledClassDemo {\n\n\t@Test\n\tvoid testWillBeSkipped() {\n\t}\n\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/DisabledTestsDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\n// tag::user_guide[]\nimport org.junit.jupiter.api.Disabled;\nimport org.junit.jupiter.api.Test;\n\nclass DisabledTestsDemo {\n\n\t@Disabled(\"Disabled until bug #42 has been resolved\")\n\t@Test\n\tvoid testWillBeSkipped() {\n\t}\n\n\t@Test\n\tvoid testWillBeExecuted() {\n\t}\n\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/DisplayNameDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\n// tag::user_guide[]\nimport org.junit.jupiter.api.DisplayName;\nimport org.junit.jupiter.api.Test;\n\n@DisplayName(\"A special test case\")\nclass DisplayNameDemo {\n\n\t@Test\n\t@DisplayName(\"Custom test name containing spaces\")\n\tvoid testWithDisplayNameContainingSpaces() {\n\t}\n\n\t@Test\n\t@DisplayName(\"╯°□°）╯\")\n\tvoid testWithDisplayNameContainingSpecialCharacters() {\n\t}\n\n\t@Test\n\t@DisplayName(\"😱\")\n\tvoid testWithDisplayNameContainingEmoji() {\n\t}\n\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/DisplayNameGeneratorDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\nimport org.junit.jupiter.api.DisplayName;\nimport org.junit.jupiter.api.DisplayNameGeneration;\nimport org.junit.jupiter.api.DisplayNameGenerator;\nimport org.junit.jupiter.api.DisplayNameGenerator.IndicativeSentences.SentenceFragment;\nimport org.junit.jupiter.api.DisplayNameGenerator.ReplaceUnderscores;\nimport org.junit.jupiter.api.IndicativeSentencesGeneration;\nimport org.junit.jupiter.api.Nested;\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.params.ParameterizedTest;\nimport org.junit.jupiter.params.provider.ValueSource;\n\nclass DisplayNameGeneratorDemo {\n\n\t@Nested\n\t// tag::user_guide_replace_underscores[]\n\t@DisplayNameGeneration(DisplayNameGenerator.ReplaceUnderscores.class)\n\tclass A_year_is_not_supported {\n\n\t\t@Test\n\t\tvoid if_it_is_zero() {\n\t\t}\n\n\t\t@DisplayName(\"A negative value for year is not supported by the leap year computation.\")\n\t\t@ParameterizedTest(name = \"For example, year {0} is not supported.\")\n\t\t@ValueSource(ints = { -1, -4 })\n\t\tvoid if_it_is_negative(int year) {\n\t\t}\n\n\t}\n\t// end::user_guide_replace_underscores[]\n\n\t@Nested\n\t// tag::user_guide_indicative_sentences[]\n\t@IndicativeSentencesGeneration(separator = \" -> \", generator = ReplaceUnderscores.class)\n\tclass A_year_is_a_leap_year {\n\n\t\t@Test\n\t\tvoid if_it_is_divisible_by_4_but_not_by_100() {\n\t\t}\n\n\t\t@ParameterizedTest(name = \"Year {0} is a leap year.\")\n\t\t@ValueSource(ints = { 2016, 2020, 2048 })\n\t\tvoid if_it_is_one_of_the_following_years(int year) {\n\t\t}\n\n\t}\n\t// end::user_guide_indicative_sentences[]\n\n\t@Nested\n\t// tag::user_guide_custom_sentence_fragments[]\n\t@SentenceFragment(\"A year is a leap year\")\n\t@IndicativeSentencesGeneration\n\tclass LeapYearTests {\n\n\t\t@SentenceFragment(\"if it is divisible by 4 but not by 100\")\n\t\t@Test\n\t\tvoid divisibleBy4ButNotBy100() {\n\t\t}\n\n\t\t@SentenceFragment(\"if it is one of the following years\")\n\t\t@ParameterizedTest(name = \"{0}\")\n\t\t@ValueSource(ints = { 2016, 2020, 2048 })\n\t\tvoid validLeapYear(int year) {\n\t\t}\n\n\t}\n\t// end::user_guide_custom_sentence_fragments[]\n\n}\n"
},
{
"path": "documentation/src/test/java/example/DocumentationTestSuite.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\nimport org.junit.platform.suite.api.ExcludeTags;\nimport org.junit.platform.suite.api.IncludeClassNamePatterns;\nimport org.junit.platform.suite.api.SelectPackages;\nimport org.junit.platform.suite.api.Suite;\n\n/**\n * Logging Configuration \n *\n * In order for our log4j2 configuration to be used in an IDE, you must\n * set the following system property before running any tests — for\n * example, in Run Configurations in Eclipse.\n *\n *
\n * -Djava.util.logging.manager=org.apache.logging.log4j.jul.LogManager\n * \n *\n * @since 5.0\n */\n@Suite\n@SelectPackages(\"example\")\n@IncludeClassNamePatterns(\".+(Tests|Demo)$\")\n@ExcludeTags(\"exclude\")\nclass DocumentationTestSuite {\n}\n"
},
{
"path": "documentation/src/test/java/example/DynamicTestsDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\n// tag::user_guide[]\nimport static example.util.StringUtils.isPalindrome;\nimport static org.junit.jupiter.api.Assertions.assertEquals;\nimport static org.junit.jupiter.api.Assertions.assertFalse;\nimport static org.junit.jupiter.api.Assertions.assertNotNull;\nimport static org.junit.jupiter.api.Assertions.assertTrue;\nimport static org.junit.jupiter.api.DynamicContainer.dynamicContainer;\nimport static org.junit.jupiter.api.DynamicTest.dynamicTest;\nimport static org.junit.jupiter.api.parallel.ExecutionMode.CONCURRENT;\nimport static org.junit.jupiter.api.parallel.ExecutionMode.SAME_THREAD;\n\nimport java.util.Arrays;\nimport java.util.Collection;\nimport java.util.Iterator;\nimport java.util.List;\nimport java.util.Random;\nimport java.util.function.Function;\nimport java.util.stream.IntStream;\nimport java.util.stream.Stream;\n\nimport example.util.Calculator;\n\nimport org.junit.jupiter.api.DynamicNode;\nimport org.junit.jupiter.api.DynamicTest;\nimport org.junit.jupiter.api.Tag;\nimport org.junit.jupiter.api.TestFactory;\nimport org.junit.jupiter.api.function.ThrowingConsumer;\nimport org.junit.jupiter.api.parallel.Execution;\n\n// end::user_guide[]\n// @formatter:off\n// tag::user_guide[]\nclass DynamicTestsDemo {\n\n\tprivate final Calculator calculator = new Calculator();\n\n\t// This method will not be executed but produce a warning\n\t@TestFactory\n\t// end::user_guide[]\n\t@Tag(\"exclude\")\n\tDynamicTest dummy() { return dynamicTest(\"dummy\", () -> {}); }\n\t// tag::user_guide[]\n\tList dynamicTestsWithInvalidReturnType() {\n\t\treturn Arrays.asList(\"Hello\");\n\t}\n\n\t@TestFactory\n\tCollection dynamicTestsFromCollection() {\n\t\treturn Arrays.asList(\n\t\t\tdynamicTest(\"1st dynamic test\", () -> assertTrue(isPalindrome(\"madam\"))),\n\t\t\tdynamicTest(\"2nd dynamic test\", () -> assertEquals(4, calculator.multiply(2, 2)))\n\t\t);\n\t}\n\n\t@TestFactory\n\tIterable dynamicTestsFromIterable() {\n\t\treturn Arrays.asList(\n\t\t\tdynamicTest(\"3rd dynamic test\", () -> assertTrue(isPalindrome(\"madam\"))),\n\t\t\tdynamicTest(\"4th dynamic test\", () -> assertEquals(4, calculator.multiply(2, 2)))\n\t\t);\n\t}\n\n\t@TestFactory\n\tIterator dynamicTestsFromIterator() {\n\t\treturn Arrays.asList(\n\t\t\tdynamicTest(\"5th dynamic test\", () -> assertTrue(isPalindrome(\"madam\"))),\n\t\t\tdynamicTest(\"6th dynamic test\", () -> assertEquals(4, calculator.multiply(2, 2)))\n\t\t).iterator();\n\t}\n\n\t@TestFactory\n\tDynamicTest[] dynamicTestsFromArray() {\n\t\treturn new DynamicTest[] {\n\t\t\tdynamicTest(\"7th dynamic test\", () -> assertTrue(isPalindrome(\"madam\"))),\n\t\t\tdynamicTest(\"8th dynamic test\", () -> assertEquals(4, calculator.multiply(2, 2)))\n\t\t};\n\t}\n\n\t@TestFactory\n\tStream dynamicTestsFromStream() {\n\t\treturn Stream.of(\"racecar\", \"radar\", \"mom\", \"dad\")\n\t\t\t.map(text -> dynamicTest(text, () -> assertTrue(isPalindrome(text))));\n\t}\n\n\t@TestFactory\n\tStream dynamicTestsFromIntStream() {\n\t\t// Generates tests for the first 10 even integers.\n\t\treturn IntStream.iterate(0, n -> n + 2).limit(10)\n\t\t\t.mapToObj(n -> dynamicTest(\"test\" + n, () -> assertEquals(0, n % 2)));\n\t}\n\n\t@TestFactory\n\tStream generateRandomNumberOfTests() {\n\n\t\t// Generates random positive integers between 0 and 100 until\n\t\t// a number evenly divisible by 7 is encountered.\n\t\tIterator inputGenerator = new Iterator<>() {\n\n\t\t\tRandom random = new Random();\n\t\t\t// end::user_guide[]\n\t\t\t{\n\t\t\t\t// Use fixed seed to always produce the same number of tests for execution on the CI server\n\t\t\t\trandom = new Random(23);\n\t\t\t}\n\t\t\t// tag::user_guide[]\n\t\t\tint current;\n\n\t\t\t@Override\n\t\t\tpublic boolean hasNext() {\n\t\t\t\tcurrent = random.nextInt(100);\n\t\t\t\treturn current % 7 != 0;\n\t\t\t}\n\n\t\t\t@Override\n\t\t\tpublic Integer next() {\n\t\t\t\treturn current;\n\t\t\t}\n\t\t};\n\n\t\t// Generates display names like: input:5, input:37, input:85, etc.\n\t\tFunction displayNameGenerator = (input) -> \"input:\" + input;\n\n\t\t// Executes tests based on the current input value.\n\t\tThrowingConsumer testExecutor = (input) -> assertTrue(input % 7 != 0);\n\n\t\t// Returns a stream of dynamic tests.\n\t\treturn DynamicTest.stream(inputGenerator, displayNameGenerator, testExecutor);\n\t}\n\n\t@TestFactory\n\tStream dynamicTestsFromStreamFactoryMethod() {\n\t\t// Stream of palindromes to check\n\t\tStream inputStream = Stream.of(\"racecar\", \"radar\", \"mom\", \"dad\");\n\n\t\t// Generates display names like: racecar is a palindrome\n\t\tFunction displayNameGenerator = text -> text + \" is a palindrome\";\n\n\t\t// Executes tests based on the current input value.\n\t\tThrowingConsumer testExecutor = text -> assertTrue(isPalindrome(text));\n\n\t\t// Returns a stream of dynamic tests.\n\t\treturn DynamicTest.stream(inputStream, displayNameGenerator, testExecutor);\n\t}\n\n\t@TestFactory\n\tStream dynamicTestsWithContainers() {\n\t\treturn Stream.of(\"A\", \"B\", \"C\")\n\t\t\t.map(input -> dynamicContainer(\"Container \" + input, Stream.of(\n\t\t\t\tdynamicTest(\"not null\", () -> assertNotNull(input)),\n\t\t\t\tdynamicContainer(\"properties\", Stream.of(\n\t\t\t\t\tdynamicTest(\"length > 0\", () -> assertTrue(input.length() > 0)),\n\t\t\t\t\tdynamicTest(\"not empty\", () -> assertFalse(input.isEmpty()))\n\t\t\t\t))\n\t\t\t)));\n\t}\n\n\t// end::user_guide[]\n\t// tag::execution_mode[]\n\t@TestFactory\n\t@Execution(CONCURRENT) // <1>\n\tStream dynamicTestsWithConfiguredExecutionMode() {\n\t\treturn Stream.of(\"A\", \"B\", \"C\")\n\t\t\t\t.map(input ->\n\t\t\t\t\tdynamicContainer(outer -> outer\n\t\t\t\t\t\t.displayName(\"Container \" + input)\n\t\t\t\t\t\t.children(\n\t\t\t\t\t\t\tdynamicTest(config -> config\n\t\t\t\t\t\t\t\t.displayName(\"not null\")\n\t\t\t\t\t\t\t\t.executionMode(SAME_THREAD) // <2>\n\t\t\t\t\t\t\t\t.executable(() -> assertNotNull(input))\n\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\tdynamicContainer(inner -> inner\n\t\t\t\t\t\t\t\t.displayName(\"properties\")\n\t\t\t\t\t\t\t\t.executionMode(CONCURRENT) // <3>\n\t\t\t\t\t\t\t\t.childExecutionMode(SAME_THREAD) // <4>\n\t\t\t\t\t\t\t\t.children(\n\t\t\t\t\t\t\t\t\tdynamicTest(config -> config\n\t\t\t\t\t\t\t\t\t\t.displayName(\"length > 0\")\n\t\t\t\t\t\t\t\t\t\t.executionMode(CONCURRENT) // <5>\n\t\t\t\t\t\t\t\t\t\t.executable(() -> assertTrue(input.length() > 0))\n\t\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t\t\tdynamicTest(config -> config\n\t\t\t\t\t\t\t\t\t\t.displayName(\"not empty\")\n\t\t\t\t\t\t\t\t\t\t.executable(() -> assertFalse(input.isEmpty()))\n\t\t\t\t\t\t\t\t\t)\n\t\t\t\t\t\t\t\t)\n\t\t\t\t\t\t\t)\n\t\t\t\t\t\t)\n\t\t\t\t\t)\n\t\t\t\t);\n\t}\n\t// end::execution_mode[]\n\n\t// tag::user_guide[]\n\t@TestFactory\n\tDynamicNode dynamicNodeSingleTest() {\n\t\treturn dynamicTest(\"'pop' is a palindrome\", () -> assertTrue(isPalindrome(\"pop\")));\n\t}\n\n\t@TestFactory\n\tDynamicNode dynamicNodeSingleContainer() {\n\t\treturn dynamicContainer(\"palindromes\",\n\t\t\tStream.of(\"racecar\", \"radar\", \"mom\", \"dad\")\n\t\t\t\t.map(text -> dynamicTest(text, () -> assertTrue(isPalindrome(text)))\n\t\t));\n\t}\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/DynamicTestsNamedDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\n// tag::user_guide[]\n\nimport static example.util.StringUtils.isPalindrome;\nimport static org.junit.jupiter.api.Assertions.assertTrue;\nimport static org.junit.jupiter.api.Named.named;\n\nimport java.util.stream.Stream;\n\nimport org.junit.jupiter.api.DynamicTest;\nimport org.junit.jupiter.api.NamedExecutable;\nimport org.junit.jupiter.api.TestFactory;\n\npublic class DynamicTestsNamedDemo {\n\n\t@TestFactory\n\tStream dynamicTestsFromStreamFactoryMethodWithNames() {\n\t\t// Stream of palindromes to check\n\t\t// end::user_guide[]\n\t\t// @formatter:off\n\t\t// tag::user_guide[]\n\t\tvar inputStream = Stream.of(\n\t\t\tnamed(\"racecar is a palindrome\", \"racecar\"),\n\t\t\tnamed(\"radar is also a palindrome\", \"radar\"),\n\t\t\tnamed(\"mom also seems to be a palindrome\", \"mom\"),\n\t\t\tnamed(\"dad is yet another palindrome\", \"dad\")\n\t\t);\n\t\t// end::user_guide[]\n\t\t// @formatter:on\n\t\t// tag::user_guide[]\n\n\t\t// Returns a stream of dynamic tests.\n\t\treturn DynamicTest.stream(inputStream, text -> assertTrue(isPalindrome(text)));\n\t}\n\n\t@TestFactory\n\tStream dynamicTestsFromStreamFactoryMethodWithNamedExecutables() {\n\t\t// Stream of palindromes to check\n\t\t// end::user_guide[]\n\t\t// @formatter:off\n\t\t// tag::user_guide[]\n\t\tvar inputStream = Stream.of(\"racecar\", \"radar\", \"mom\", \"dad\")\n\t\t\t\t.map(PalindromeNamedExecutable::new);\n\t\t// end::user_guide[]\n\t\t// @formatter:on\n\t\t// tag::user_guide[]\n\n\t\t// Returns a stream of dynamic tests based on NamedExecutables.\n\t\treturn DynamicTest.stream(inputStream);\n\t}\n\n\trecord PalindromeNamedExecutable(String text) implements NamedExecutable {\n\n\t\t@Override\n\t\tpublic String getName() {\n\t\t\treturn \"'%s' is a palindrome\".formatted(text);\n\t\t}\n\n\t\t@Override\n\t\tpublic void execute() {\n\t\t\tassertTrue(isPalindrome(text));\n\t\t}\n\t}\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/ExampleTestCase.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\n// tag::user_guide[]\n\nimport static org.junit.jupiter.api.Assertions.assertEquals;\nimport static org.junit.jupiter.api.Assumptions.assumeTrue;\n\nimport example.util.Calculator;\n\nimport org.junit.jupiter.api.Disabled;\nimport org.junit.jupiter.api.MethodOrderer.OrderAnnotation;\nimport org.junit.jupiter.api.Order;\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.TestMethodOrder;\n\n@TestMethodOrder(OrderAnnotation.class)\npublic class ExampleTestCase {\n\n\tprivate final Calculator calculator = new Calculator();\n\n\t@Test\n\t@Disabled(\"for demonstration purposes\")\n\t@Order(1)\n\tvoid skippedTest() {\n\t\t// skipped ...\n\t}\n\n\t@Test\n\t@Order(2)\n\tvoid succeedingTest() {\n\t\tassertEquals(42, calculator.multiply(6, 7));\n\t}\n\n\t@Test\n\t@Order(3)\n\tvoid abortedTest() {\n\t\tassumeTrue(\"abc\".contains(\"Z\"), \"abc does not contain Z\");\n\t\t// aborted ...\n\t}\n\n\t@Test\n\t@Order(4)\n\tvoid failingTest() {\n\t\t// The following throws an ArithmeticException: \"/ by zero\"\n\t\tcalculator.divide(1, 0);\n\t}\n\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/ExplicitExecutionModeDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.parallel.Execution;\nimport org.junit.jupiter.api.parallel.ExecutionMode;\n\n//tag::user_guide[]\n@Execution(ExecutionMode.CONCURRENT)\nclass ExplicitExecutionModeDemo {\n\n\t@Test\n\tvoid testA() {\n\t\t// concurrent\n\t}\n\n\t@Test\n\t@Execution(ExecutionMode.SAME_THREAD)\n\tvoid testB() {\n\t\t// overrides to same_thread\n\t}\n\n}\n//end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/ExternalCustomConditionDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\n// tag::user_guide_external_custom_condition[]\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.condition.EnabledIf;\n\nclass ExternalCustomConditionDemo {\n\n\t@Test\n\t@EnabledIf(\"example.ExternalCondition#customCondition\")\n\tvoid enabled() {\n\t\t// ...\n\t}\n\n}\n\nclass ExternalCondition {\n\n\tstatic boolean customCondition() {\n\t\treturn true;\n\t}\n\n}\n// end::user_guide_external_custom_condition[]\n"
},
{
"path": "documentation/src/test/java/example/ExternalFieldSourceDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\nimport java.util.List;\n\nimport org.junit.jupiter.params.ParameterizedTest;\nimport org.junit.jupiter.params.provider.FieldSource;\n\nclass ExternalFieldSourceDemo {\n\n\t// tag::external_field_FieldSource_example[]\n\t@ParameterizedTest\n\t@FieldSource(\"example.FruitUtils#tropicalFruits\")\n\tvoid testWithExternalFieldSource(String tropicalFruit) {\n\t\t// test with tropicalFruit\n\t}\n\t// end::external_field_FieldSource_example[]\n}\n\nclass FruitUtils {\n\n\tpublic static final List tropicalFruits = List.of(\"pineapple\", \"kiwi\");\n\n}\n"
},
{
"path": "documentation/src/test/java/example/ExternalMethodSourceDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\n// tag::external_MethodSource_example[]\nimport java.util.stream.Stream;\n\nimport org.junit.jupiter.params.ParameterizedTest;\nimport org.junit.jupiter.params.provider.MethodSource;\n\nclass ExternalMethodSourceDemo {\n\n\t@ParameterizedTest\n\t@MethodSource(\"example.StringsProviders#tinyStrings\")\n\tvoid testWithExternalMethodSource(String tinyString) {\n\t\t// test with tiny string\n\t}\n}\n\nclass StringsProviders {\n\n\tstatic Stream tinyStrings() {\n\t\treturn Stream.of(\".\", \"oo\", \"OOO\");\n\t}\n}\n// end::external_MethodSource_example[]\n"
},
{
"path": "documentation/src/test/java/example/Fast.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\n// tag::user_guide[]\nimport java.lang.annotation.ElementType;\nimport java.lang.annotation.Retention;\nimport java.lang.annotation.RetentionPolicy;\nimport java.lang.annotation.Target;\n\nimport org.junit.jupiter.api.Tag;\n\n@Target({ ElementType.TYPE, ElementType.METHOD })\n@Retention(RetentionPolicy.RUNTIME)\n@Tag(\"fast\")\npublic @interface Fast {\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/FastTest.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\n// tag::user_guide[]\nimport java.lang.annotation.ElementType;\nimport java.lang.annotation.Retention;\nimport java.lang.annotation.RetentionPolicy;\nimport java.lang.annotation.Target;\n\nimport org.junit.jupiter.api.Tag;\nimport org.junit.jupiter.api.Test;\n\n@Target(ElementType.METHOD)\n@Retention(RetentionPolicy.RUNTIME)\n@Tag(\"fast\")\n@Test\npublic @interface FastTest {\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/FirstCustomEngine.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\n//tag::user_guide[]\nimport static java.net.InetAddress.getLoopbackAddress;\nimport static org.junit.platform.engine.TestExecutionResult.successful;\n\nimport java.io.IOException;\nimport java.io.UncheckedIOException;\nimport java.net.ServerSocket;\n\nimport org.jspecify.annotations.Nullable;\nimport org.junit.platform.engine.EngineDiscoveryRequest;\nimport org.junit.platform.engine.ExecutionRequest;\nimport org.junit.platform.engine.TestDescriptor;\nimport org.junit.platform.engine.TestEngine;\nimport org.junit.platform.engine.UniqueId;\nimport org.junit.platform.engine.support.descriptor.EngineDescriptor;\nimport org.junit.platform.engine.support.store.Namespace;\nimport org.junit.platform.engine.support.store.NamespacedHierarchicalStore;\n\n/**\n * First custom test engine implementation.\n */\npublic class FirstCustomEngine implements TestEngine {\n\n\t//end::user_guide[]\n\t@Nullable\n\t//tag::user_guide[]\n\tpublic ServerSocket socket;\n\n\t@Override\n\tpublic String getId() {\n\t\treturn \"first-custom-test-engine\";\n\t}\n\n\t//end::user_guide[]\n\t@Nullable\n\t//tag::user_guide[]\n\tpublic ServerSocket getSocket() {\n\t\treturn this.socket;\n\t}\n\n\t@Override\n\tpublic TestDescriptor discover(EngineDiscoveryRequest discoveryRequest, UniqueId uniqueId) {\n\t\treturn new EngineDescriptor(uniqueId, \"First Custom Test Engine\");\n\t}\n\n\t@Override\n\tpublic void execute(ExecutionRequest request) {\n\t\trequest.getEngineExecutionListener()\n\t\t\t\t// tag::custom_line_break[]\n\t\t\t\t.executionStarted(request.getRootTestDescriptor());\n\n\t\tNamespacedHierarchicalStore store = request.getStore();\n\t\tsocket = store.computeIfAbsent(Namespace.GLOBAL, \"serverSocket\", key -> {\n\t\t\ttry {\n\t\t\t\treturn new ServerSocket(0, 50, getLoopbackAddress());\n\t\t\t}\n\t\t\tcatch (IOException e) {\n\t\t\t\tthrow new UncheckedIOException(\"Failed to start ServerSocket\", e);\n\t\t\t}\n\t\t}, ServerSocket.class);\n\n\t\trequest.getEngineExecutionListener()\n\t\t\t\t// tag::custom_line_break[]\n\t\t\t\t.executionFinished(request.getRootTestDescriptor(), successful());\n\t}\n\n}\n//end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/HttpServerDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\nimport static java.nio.charset.StandardCharsets.UTF_8;\nimport static org.junit.jupiter.api.Assertions.assertEquals;\n\nimport java.io.IOException;\nimport java.io.InputStream;\nimport java.net.HttpURLConnection;\nimport java.net.URI;\nimport java.net.URL;\n\nimport com.sun.net.httpserver.HttpServer;\n\nimport example.extensions.HttpServerExtension;\n\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.extension.ExtendWith;\n\n// tag::user_guide[]\n@ExtendWith(HttpServerExtension.class)\npublic class HttpServerDemo {\n\n\t// end::user_guide[]\n\t@SuppressWarnings(\"HttpUrlsUsage\")\n\t// tag::user_guide[]\n\t@Test\n\tvoid httpCall(HttpServer server) throws Exception {\n\t\tString hostName = server.getAddress().getHostName();\n\t\tint port = server.getAddress().getPort();\n\t\tString rawUrl = \"http://%s:%d/example\".formatted(hostName, port);\n\t\tURL requestUrl = URI.create(rawUrl).toURL();\n\n\t\tString responseBody = sendRequest(requestUrl);\n\n\t\tassertEquals(\"This is a test\", responseBody);\n\t}\n\n\tprivate static String sendRequest(URL url) throws IOException {\n\t\tHttpURLConnection connection = (HttpURLConnection) url.openConnection();\n\t\tint contentLength = connection.getContentLength();\n\t\ttry (InputStream response = url.openStream()) {\n\t\t\tbyte[] content = new byte[contentLength];\n\t\t\tassertEquals(contentLength, response.read(content));\n\t\t\treturn new String(content, UTF_8);\n\t\t}\n\t}\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/IgnoredTestsDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\n// tag::user_guide[]\nimport org.junit.Ignore;\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.migrationsupport.EnableJUnit4MigrationSupport;\n\n// @ExtendWith(IgnoreCondition.class)\n@SuppressWarnings(\"removal\")\n@EnableJUnit4MigrationSupport\nclass IgnoredTestsDemo {\n\n\t@Ignore\n\t@Test\n\tvoid testWillBeIgnored() {\n\t}\n\n\t@Test\n\tvoid testWillBeExecuted() {\n\t}\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/JUnit4Tests.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\nimport org.junit.Test;\n\npublic class JUnit4Tests {\n\n\t@Test\n\tpublic void standardJUnit4Test() {\n\t\t// perform assertions\n\t}\n\n}\n"
},
{
"path": "documentation/src/test/java/example/MethodSourceParameterResolutionDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\nimport static org.junit.jupiter.api.Assertions.assertTrue;\nimport static org.junit.jupiter.params.provider.Arguments.arguments;\n\nimport java.util.stream.Stream;\n\nimport org.junit.jupiter.api.extension.ExtensionContext;\nimport org.junit.jupiter.api.extension.ParameterContext;\nimport org.junit.jupiter.api.extension.ParameterResolver;\nimport org.junit.jupiter.api.extension.RegisterExtension;\nimport org.junit.jupiter.params.ParameterizedTest;\nimport org.junit.jupiter.params.provider.Arguments;\nimport org.junit.jupiter.params.provider.MethodSource;\n\nclass MethodSourceParameterResolutionDemo {\n\n\t// @formatter:off\n\t// tag::parameter_resolution_MethodSource_example[]\n\t@RegisterExtension\n\tstatic final IntegerResolver integerResolver = new IntegerResolver();\n\n\t@ParameterizedTest\n\t@MethodSource(\"factoryMethodWithArguments\")\n\tvoid testWithFactoryMethodWithArguments(String argument) {\n\t\tassertTrue(argument.startsWith(\"2\"));\n\t}\n\n\tstatic Stream factoryMethodWithArguments(int quantity) {\n\t\treturn Stream.of(\n\t\t\t\targuments(quantity + \" apples\"),\n\t\t\t\targuments(quantity + \" lemons\")\n\t\t);\n\t}\n\n\tstatic class IntegerResolver implements ParameterResolver {\n\n\t\t@Override\n\t\tpublic boolean supportsParameter(ParameterContext parameterContext,\n\t\t\t\tExtensionContext extensionContext) {\n\n\t\t\treturn parameterContext.getParameter().getType() == int.class;\n\t\t}\n\n\t\t@Override\n\t\tpublic Object resolveParameter(ParameterContext parameterContext,\n\t\t\t\tExtensionContext extensionContext) {\n\n\t\t\treturn 2;\n\t\t}\n\n\t}\n\t// end::parameter_resolution_MethodSource_example[]\n\t// @formatter:on\n\n}\n"
},
{
"path": "documentation/src/test/java/example/MyFirstJUnitJupiterRecordTests.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\n// tag::user_guide[]\nimport static org.junit.jupiter.api.Assertions.assertEquals;\n\nimport example.util.Calculator;\n\nimport org.junit.jupiter.api.Test;\n\nrecord MyFirstJUnitJupiterRecordTests() {\n\n\t@Test\n\tvoid addition() {\n\t\tassertEquals(2, new Calculator().add(1, 1));\n\t}\n\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/MyFirstJUnitJupiterTests.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\n// tag::user_guide[]\nimport static org.junit.jupiter.api.Assertions.assertEquals;\n\nimport example.util.Calculator;\n\nimport org.junit.jupiter.api.Test;\n\nclass MyFirstJUnitJupiterTests {\n\n\tprivate final Calculator calculator = new Calculator();\n\n\t@Test\n\tvoid addition() {\n\t\tassertEquals(2, calculator.add(1, 1));\n\t}\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/MyRandomParametersTest.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\nimport static org.junit.jupiter.api.Assertions.assertNotEquals;\n\nimport example.extensions.Random;\n\nimport org.junit.jupiter.api.Test;\n\n// tag::user_guide[]\nclass MyRandomParametersTest {\n\n\tMyRandomParametersTest(@Random int randomNumber) {\n\t\t// Use randomNumber in constructor.\n\t}\n\n\t@Test\n\tvoid injectsInteger(@Random int i, @Random int j) {\n\t\tassertNotEquals(i, j);\n\t}\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/OrderedNestedTestClassesDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\n// tag::user_guide[]\nimport org.junit.jupiter.api.ClassOrderer;\nimport org.junit.jupiter.api.Nested;\nimport org.junit.jupiter.api.Order;\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.TestClassOrder;\n\n@TestClassOrder(ClassOrderer.OrderAnnotation.class)\nclass OrderedNestedTestClassesDemo {\n\n\t@Nested\n\t@Order(1)\n\tclass PrimaryTests {\n\n\t\t@Test\n\t\tvoid test1() {\n\t\t}\n\t}\n\n\t@Nested\n\t@Order(2)\n\tclass SecondaryTests {\n\n\t\t@Test\n\t\tvoid test2() {\n\t\t}\n\t}\n}\n//end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/OrderedTestsDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\n// tag::user_guide[]\nimport org.junit.jupiter.api.MethodOrderer.OrderAnnotation;\nimport org.junit.jupiter.api.Order;\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.TestMethodOrder;\n\n@TestMethodOrder(OrderAnnotation.class)\nclass OrderedTestsDemo {\n\n\t@Test\n\t@Order(1)\n\tvoid nullValues() {\n\t\t// perform assertions against null values\n\t}\n\n\t@Test\n\t@Order(2)\n\tvoid emptyValues() {\n\t\t// perform assertions against empty values\n\t}\n\n\t@Test\n\t@Order(3)\n\tvoid validValues() {\n\t\t// perform assertions against valid values\n\t}\n\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/ParameterizedClassDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\nimport static org.junit.jupiter.api.Assertions.assertFalse;\nimport static org.junit.jupiter.api.Assertions.assertTrue;\nimport static org.junit.jupiter.api.parallel.ExecutionMode.SAME_THREAD;\n\nimport java.time.Duration;\nimport java.util.Arrays;\n\nimport example.util.StringUtils;\n\nimport org.junit.jupiter.api.Nested;\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.parallel.Execution;\nimport org.junit.jupiter.params.Parameter;\nimport org.junit.jupiter.params.ParameterizedClass;\nimport org.junit.jupiter.params.ParameterizedTest;\nimport org.junit.jupiter.params.provider.CsvSource;\nimport org.junit.jupiter.params.provider.ValueSource;\n\npublic class ParameterizedClassDemo {\n\n\t@Nested\n\t// tag::first_example[]\n\t@ParameterizedClass\n\t@ValueSource(strings = { \"racecar\", \"radar\", \"able was I ere I saw elba\" })\n\tclass PalindromeTests {\n\n\t\t@Parameter\n\t\tString candidate;\n\n\t\t@Test\n\t\tvoid palindrome() {\n\t\t\tassertTrue(StringUtils.isPalindrome(candidate));\n\t\t}\n\n\t\t@Test\n\t\tvoid reversePalindrome() {\n\t\t\tString reverseCandidate = new StringBuilder(candidate).reverse().toString();\n\t\t\tassertTrue(StringUtils.isPalindrome(reverseCandidate));\n\t\t}\n\t}\n\t// end::first_example[]\n\n\t@Nested\n\tclass ConstructorInjection {\n\t\t@Nested\n\t\t// tag::constructor_injection[]\n\t\t@ParameterizedClass\n\t\t@CsvSource({ \"apple, 23\", \"banana, 42\" })\n\t\tclass FruitTests {\n\n\t\t\tfinal String fruit;\n\t\t\tfinal int quantity;\n\n\t\t\tFruitTests(String fruit, int quantity) {\n\t\t\t\tthis.fruit = fruit;\n\t\t\t\tthis.quantity = quantity;\n\t\t\t}\n\n\t\t\t@Test\n\t\t\tvoid test() {\n\t\t\t\tassertFruit(fruit);\n\t\t\t\tassertQuantity(quantity);\n\t\t\t}\n\n\t\t\t@Test\n\t\t\tvoid anotherTest() {\n\t\t\t\t// ...\n\t\t\t}\n\t\t}\n\t\t// end::constructor_injection[]\n\t}\n\n\t@Nested\n\tclass FieldInjection {\n\t\t@Nested\n\t\t// tag::field_injection[]\n\t\t@ParameterizedClass\n\t\t@CsvSource({ \"apple, 23\", \"banana, 42\" })\n\t\tclass FruitTests {\n\n\t\t\t@Parameter(0)\n\t\t\tString fruit;\n\n\t\t\t@Parameter(1)\n\t\t\tint quantity;\n\n\t\t\t@Test\n\t\t\tvoid test() {\n\t\t\t\tassertFruit(fruit);\n\t\t\t\tassertQuantity(quantity);\n\t\t\t}\n\n\t\t\t@Test\n\t\t\tvoid anotherTest() {\n\t\t\t\t// ...\n\t\t\t}\n\t\t}\n\t\t// end::field_injection[]\n\t}\n\n\t@Nested\n\t// tag::nested[]\n\t@Execution(SAME_THREAD)\n\t@ParameterizedClass\n\t@ValueSource(strings = { \"apple\", \"banana\" })\n\tclass FruitTests {\n\n\t\t@Parameter\n\t\tString fruit;\n\n\t\t@Nested\n\t\t@ParameterizedClass\n\t\t@ValueSource(ints = { 23, 42 })\n\t\tclass QuantityTests {\n\n\t\t\t@Parameter\n\t\t\tint quantity;\n\n\t\t\t@ParameterizedTest\n\t\t\t@ValueSource(strings = { \"PT1H\", \"PT2H\" })\n\t\t\tvoid test(Duration duration) {\n\t\t\t\tassertFruit(fruit);\n\t\t\t\tassertQuantity(quantity);\n\t\t\t\tassertFalse(duration.isNegative());\n\t\t\t}\n\t\t}\n\t}\n\t// end::nested[]\n\n\tstatic void assertFruit(String fruit) {\n\t\tassertTrue(Arrays.asList(\"apple\", \"banana\", \"cherry\", \"dewberry\").contains(fruit),\n\t\t\t() -> \"not a fruit: \" + fruit);\n\t}\n\n\tstatic void assertQuantity(int quantity) {\n\t\tassertTrue(quantity > 0);\n\t}\n}\n"
},
{
"path": "documentation/src/test/java/example/ParameterizedLifecycleDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\nimport static org.junit.jupiter.api.Assertions.assertEquals;\nimport static org.junit.jupiter.api.Assertions.assertTrue;\n\nimport java.nio.file.Files;\nimport java.nio.file.Path;\nimport java.util.List;\n\nimport org.jspecify.annotations.Nullable;\nimport org.junit.jupiter.api.Nested;\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.io.TempDir;\nimport org.junit.jupiter.params.AfterParameterizedClassInvocation;\nimport org.junit.jupiter.params.BeforeParameterizedClassInvocation;\nimport org.junit.jupiter.params.Parameter;\nimport org.junit.jupiter.params.ParameterizedClass;\nimport org.junit.jupiter.params.provider.MethodSource;\n\npublic class ParameterizedLifecycleDemo {\n\n\t@Nested\n\t// tag::example[]\n\t@ParameterizedClass\n\t@MethodSource(\"textFiles\")\n\tclass TextFileTests {\n\n\t\tstatic List textFiles() {\n\t\t\treturn List.of(\n\t\t\t\t// tag::custom_line_break[]\n\t\t\t\tnew TextFile(\"file1\", \"first content\"),\n\t\t\t\t// tag::custom_line_break[]\n\t\t\t\tnew TextFile(\"file2\", \"second content\")\n\t\t\t// tag::custom_line_break[]\n\t\t\t);\n\t\t}\n\n\t\t@Parameter\n\t\tTextFile textFile;\n\n\t\t@BeforeParameterizedClassInvocation\n\t\tstatic void beforeInvocation(TextFile textFile, @TempDir Path tempDir) throws Exception {\n\t\t\tvar filePath = tempDir.resolve(textFile.fileName); // <1>\n\t\t\ttextFile.path = Files.writeString(filePath, textFile.content);\n\t\t}\n\n\t\t//end::user_guide[]\n\t\t@SuppressWarnings(\"DataFlowIssue\")\n\t\t//tag::user_guide[]\n\t\t@AfterParameterizedClassInvocation\n\t\tstatic void afterInvocation(TextFile textFile) throws Exception {\n\t\t\tvar actualContent = Files.readString(textFile.path); // <3>\n\t\t\tassertEquals(textFile.content, actualContent, \"Content must not have changed\");\n\t\t\t// Custom cleanup logic, if necessary\n\t\t\t// File will be deleted automatically by @TempDir support\n\t\t}\n\n\t\t//end::user_guide[]\n\t\t@SuppressWarnings(\"DataFlowIssue\")\n\t\t//tag::user_guide[]\n\t\t@Test\n\t\tvoid test() {\n\t\t\tassertTrue(Files.exists(textFile.path)); // <2>\n\t\t}\n\n\t\t@Test\n\t\tvoid anotherTest() {\n\t\t\t// ...\n\t\t}\n\n\t\tstatic class TextFile {\n\n\t\t\tfinal String fileName;\n\t\t\tfinal String content;\n\t\t\t// end::example[]\n\t\t\t@Nullable\n\t\t\t// tag::example[]\n\t\t\tPath path;\n\n\t\t\tTextFile(String fileName, String content) {\n\t\t\t\tthis.fileName = fileName;\n\t\t\t\tthis.content = content;\n\t\t\t}\n\n\t\t\t@Override\n\t\t\tpublic String toString() {\n\t\t\t\treturn fileName;\n\t\t\t}\n\t\t}\n\t}\n\t// end::example[]\n\n}\n"
},
{
"path": "documentation/src/test/java/example/ParameterizedMigrationDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\nimport java.util.Arrays;\n\nimport org.junit.jupiter.params.AfterParameterizedClassInvocation;\nimport org.junit.jupiter.params.BeforeParameterizedClassInvocation;\nimport org.junit.jupiter.params.ParameterizedClass;\nimport org.junit.jupiter.params.provider.MethodSource;\nimport org.junit.runner.RunWith;\nimport org.junit.runners.Parameterized;\n\npublic class ParameterizedMigrationDemo {\n\n\t// tag::before[]\n\t@RunWith(Parameterized.class)\n\t// end::before[]\n\tstatic\n\t// tag::before[]\n\tpublic class JUnit4ParameterizedClassTests {\n\n\t\t@Parameterized.Parameters\n\t\tpublic static Iterable data() {\n\t\t\treturn Arrays.asList(new Object[][] { { 1, \"foo\" }, { 2, \"bar\" } });\n\t\t}\n\n\t\t// end::before[]\n\t\t@SuppressWarnings(\"DefaultAnnotationParam\")\n\t\t// tag::before[]\n\t\t@Parameterized.Parameter(0)\n\t\tpublic int number;\n\n\t\t@Parameterized.Parameter(1)\n\t\tpublic String text;\n\n\t\t@Parameterized.BeforeParam\n\t\tpublic static void before(int number, String text) {\n\t\t}\n\n\t\t@Parameterized.AfterParam\n\t\tpublic static void after() {\n\t\t}\n\n\t\t@org.junit.Test\n\t\tpublic void someTest() {\n\t\t}\n\n\t\t@org.junit.Test\n\t\tpublic void anotherTest() {\n\t\t}\n\t}\n\t// end::before[]\n\n\t// tag::after[]\n\t@ParameterizedClass\n\t@MethodSource(\"data\")\n\t// end::after[]\n\tstatic\n\t// tag::after[]\n\tclass JupiterParameterizedClassTests {\n\n\t\tstatic Iterable data() {\n\t\t\treturn Arrays.asList(new Object[][] { { 1, \"foo\" }, { 2, \"bar\" } });\n\t\t}\n\n\t\t@org.junit.jupiter.params.Parameter(0)\n\t\tint number;\n\n\t\t@org.junit.jupiter.params.Parameter(1)\n\t\tString text;\n\n\t\t@BeforeParameterizedClassInvocation\n\t\tstatic void before(int number, String text) {\n\t\t}\n\n\t\t@AfterParameterizedClassInvocation\n\t\tstatic void after() {\n\t\t}\n\n\t\t@org.junit.jupiter.api.Test\n\t\tvoid someTest() {\n\t\t}\n\n\t\t@org.junit.jupiter.api.Test\n\t\tvoid anotherTest() {\n\t\t}\n\t}\n\t// end::after[]\n\n}\n"
},
{
"path": "documentation/src/test/java/example/ParameterizedRecordDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\nimport static org.junit.jupiter.api.Assertions.assertTrue;\n\nimport java.util.Arrays;\n\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.params.ParameterizedClass;\nimport org.junit.jupiter.params.provider.CsvSource;\n\npublic class ParameterizedRecordDemo {\n\n\t// tag::example[]\n\t@ParameterizedClass\n\t@CsvSource({ \"apple, 23\", \"banana, 42\" })\n\trecord FruitTests(String fruit, int quantity) {\n\n\t\t@Test\n\t\tvoid test() {\n\t\t\tassertFruit(fruit);\n\t\t\tassertQuantity(quantity);\n\t\t}\n\n\t\t@Test\n\t\tvoid anotherTest() {\n\t\t\t// ...\n\t\t}\n\t}\n\t// end::example[]\n\n\tstatic void assertFruit(String fruit) {\n\t\tassertTrue(Arrays.asList(\"apple\", \"banana\", \"cherry\", \"dewberry\").contains(fruit));\n\t}\n\n\tstatic void assertQuantity(int quantity) {\n\t\tassertTrue(quantity >= 0);\n\t}\n}\n"
},
{
"path": "documentation/src/test/java/example/ParameterizedTestDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\nimport static org.junit.jupiter.api.Assertions.assertEquals;\nimport static org.junit.jupiter.api.Assertions.assertFalse;\nimport static org.junit.jupiter.api.Assertions.assertNotEquals;\nimport static org.junit.jupiter.api.Assertions.assertNotNull;\nimport static org.junit.jupiter.api.Assertions.assertTrue;\nimport static org.junit.jupiter.api.Named.named;\nimport static org.junit.jupiter.api.parallel.ExecutionMode.SAME_THREAD;\nimport static org.junit.jupiter.params.provider.Arguments.argumentSet;\nimport static org.junit.jupiter.params.provider.Arguments.arguments;\nimport static org.junit.jupiter.params.provider.EnumSource.Mode.EXCLUDE;\nimport static org.junit.jupiter.params.provider.EnumSource.Mode.MATCH_ALL;\n\nimport java.io.File;\nimport java.lang.annotation.ElementType;\nimport java.lang.annotation.Retention;\nimport java.lang.annotation.RetentionPolicy;\nimport java.lang.annotation.Target;\nimport java.time.LocalDate;\nimport java.time.temporal.ChronoUnit;\nimport java.time.temporal.TemporalUnit;\nimport java.util.Arrays;\nimport java.util.Collection;\nimport java.util.EnumSet;\nimport java.util.List;\nimport java.util.function.Supplier;\nimport java.util.stream.IntStream;\nimport java.util.stream.Stream;\n\nimport example.domain.Person;\nimport example.domain.Person.Gender;\nimport example.util.StringUtils;\n\nimport org.junit.jupiter.api.AfterEach;\nimport org.junit.jupiter.api.BeforeEach;\nimport org.junit.jupiter.api.Disabled;\nimport org.junit.jupiter.api.DisplayName;\nimport org.junit.jupiter.api.Nested;\nimport org.junit.jupiter.api.TestInfo;\nimport org.junit.jupiter.api.TestReporter;\nimport org.junit.jupiter.api.extension.AnnotatedElementContext;\nimport org.junit.jupiter.api.extension.ExtensionContext;\nimport org.junit.jupiter.api.parallel.Execution;\nimport org.junit.jupiter.params.ArgumentCountValidationMode;\nimport org.junit.jupiter.params.ParameterizedTest;\nimport org.junit.jupiter.params.aggregator.AggregateWith;\nimport org.junit.jupiter.params.aggregator.ArgumentsAccessor;\nimport org.junit.jupiter.params.aggregator.SimpleArgumentsAggregator;\nimport org.junit.jupiter.params.converter.ConvertWith;\nimport org.junit.jupiter.params.converter.JavaTimeConversionPattern;\nimport org.junit.jupiter.params.converter.SimpleArgumentConverter;\nimport org.junit.jupiter.params.converter.TypedArgumentConverter;\nimport org.junit.jupiter.params.provider.Arguments;\nimport org.junit.jupiter.params.provider.ArgumentsProvider;\nimport org.junit.jupiter.params.provider.ArgumentsSource;\nimport org.junit.jupiter.params.provider.CsvFileSource;\nimport org.junit.jupiter.params.provider.CsvSource;\nimport org.junit.jupiter.params.provider.EmptySource;\nimport org.junit.jupiter.params.provider.EnumSource;\nimport org.junit.jupiter.params.provider.FieldSource;\nimport org.junit.jupiter.params.provider.MethodSource;\nimport org.junit.jupiter.params.provider.NullAndEmptySource;\nimport org.junit.jupiter.params.provider.NullSource;\nimport org.junit.jupiter.params.provider.ValueSource;\nimport org.junit.jupiter.params.support.ParameterDeclarations;\n\n@Execution(SAME_THREAD)\nclass ParameterizedTestDemo {\n\n\t@BeforeEach\n\tvoid printDisplayName(TestInfo testInfo) {\n\t\tSystem.out.println(testInfo.getDisplayName());\n\t}\n\n\t// tag::first_example[]\n\t@ParameterizedTest\n\t@ValueSource(strings = { \"racecar\", \"radar\", \"able was I ere I saw elba\" })\n\tvoid palindromes(String candidate) {\n\t\tassertTrue(StringUtils.isPalindrome(candidate));\n\t}\n\t// end::first_example[]\n\n\t// tag::ValueSource_example[]\n\t@ParameterizedTest\n\t@ValueSource(ints = { 1, 2, 3 })\n\tvoid testWithValueSource(int argument) {\n\t\tassertTrue(argument > 0 && argument < 4);\n\t}\n\t// end::ValueSource_example[]\n\n\t@Nested\n\tclass NullAndEmptySource_1 {\n\n\t\t// tag::NullAndEmptySource_example1[]\n\t\t@ParameterizedTest\n\t\t@NullSource\n\t\t@EmptySource\n\t\t@ValueSource(strings = { \" \", \" \", \"\\t\", \"\\n\" })\n\t\tvoid nullEmptyAndBlankStrings(String text) {\n\t\t\tassertTrue(text == null || text.isBlank());\n\t\t}\n\t\t// end::NullAndEmptySource_example1[]\n\t}\n\n\t@Nested\n\tclass NullAndEmptySource_2 {\n\n\t\t// tag::NullAndEmptySource_example2[]\n\t\t@ParameterizedTest\n\t\t@NullAndEmptySource\n\t\t@ValueSource(strings = { \" \", \" \", \"\\t\", \"\\n\" })\n\t\tvoid nullEmptyAndBlankStrings(String text) {\n\t\t\tassertTrue(text == null || text.isBlank());\n\t\t}\n\t\t// end::NullAndEmptySource_example2[]\n\t}\n\n\t// tag::EnumSource_example[]\n\t@ParameterizedTest\n\t@EnumSource(ChronoUnit.class)\n\tvoid testWithEnumSource(TemporalUnit unit) {\n\t\tassertNotNull(unit);\n\t}\n\t// end::EnumSource_example[]\n\n\t// tag::EnumSource_example_autodetection[]\n\t@ParameterizedTest\n\t@EnumSource\n\tvoid testWithEnumSourceWithAutoDetection(ChronoUnit unit) {\n\t\tassertNotNull(unit);\n\t}\n\t// end::EnumSource_example_autodetection[]\n\n\t// tag::EnumSource_include_example[]\n\t@ParameterizedTest\n\t@EnumSource(names = { \"DAYS\", \"HOURS\" })\n\tvoid testWithEnumSourceInclude(ChronoUnit unit) {\n\t\tassertTrue(EnumSet.of(ChronoUnit.DAYS, ChronoUnit.HOURS).contains(unit));\n\t}\n\t// end::EnumSource_include_example[]\n\n\t// tag::EnumSource_range_example[]\n\t@ParameterizedTest\n\t@EnumSource(from = \"HOURS\", to = \"DAYS\")\n\tvoid testWithEnumSourceRange(ChronoUnit unit) {\n\t\tassertTrue(EnumSet.of(ChronoUnit.HOURS, ChronoUnit.HALF_DAYS, ChronoUnit.DAYS).contains(unit));\n\t}\n\t// end::EnumSource_range_example[]\n\n\t// tag::EnumSource_exclude_example[]\n\t@ParameterizedTest\n\t@EnumSource(mode = EXCLUDE, names = { \"ERAS\", \"FOREVER\" })\n\tvoid testWithEnumSourceExclude(ChronoUnit unit) {\n\t\tassertFalse(EnumSet.of(ChronoUnit.ERAS, ChronoUnit.FOREVER).contains(unit));\n\t}\n\t// end::EnumSource_exclude_example[]\n\n\t// tag::EnumSource_regex_example[]\n\t@ParameterizedTest\n\t@EnumSource(mode = MATCH_ALL, names = \"^.*DAYS$\")\n\tvoid testWithEnumSourceRegex(ChronoUnit unit) {\n\t\tassertTrue(unit.name().endsWith(\"DAYS\"));\n\t}\n\t// end::EnumSource_regex_example[]\n\n\t// tag::EnumSource_range_exclude_example[]\n\t@ParameterizedTest\n\t@EnumSource(from = \"HOURS\", to = \"DAYS\", mode = EXCLUDE, names = { \"HALF_DAYS\" })\n\tvoid testWithEnumSourceRangeExclude(ChronoUnit unit) {\n\t\tassertTrue(EnumSet.of(ChronoUnit.HOURS, ChronoUnit.DAYS).contains(unit));\n\t\tassertFalse(EnumSet.of(ChronoUnit.HALF_DAYS).contains(unit));\n\t}\n\t// end::EnumSource_range_exclude_example[]\n\n\t// tag::simple_MethodSource_example[]\n\t@ParameterizedTest\n\t@MethodSource(\"stringProvider\")\n\tvoid testWithExplicitLocalMethodSource(String argument) {\n\t\tassertNotNull(argument);\n\t}\n\n\tstatic Stream stringProvider() {\n\t\treturn Stream.of(\"apple\", \"banana\");\n\t}\n\t// end::simple_MethodSource_example[]\n\n\t// tag::simple_MethodSource_without_value_example[]\n\t@ParameterizedTest\n\t@MethodSource\n\tvoid testWithDefaultLocalMethodSource(String argument) {\n\t\tassertNotNull(argument);\n\t}\n\n\tstatic Stream testWithDefaultLocalMethodSource() {\n\t\treturn Stream.of(\"apple\", \"banana\");\n\t}\n\t// end::simple_MethodSource_without_value_example[]\n\n\t// tag::primitive_MethodSource_example[]\n\t@ParameterizedTest\n\t@MethodSource(\"range\")\n\tvoid testWithRangeMethodSource(int argument) {\n\t\tassertNotEquals(9, argument);\n\t}\n\n\tstatic IntStream range() {\n\t\treturn IntStream.range(0, 20).skip(10);\n\t}\n\t// end::primitive_MethodSource_example[]\n\n\t// @formatter:off\n\t// tag::multi_arg_MethodSource_example[]\n\t@ParameterizedTest\n\t@MethodSource(\"stringIntAndListProvider\")\n\tvoid testWithMultiArgMethodSource(String str, int num, List list) {\n\t\tassertEquals(5, str.length());\n\t\tassertTrue(num >=1 && num <=2);\n\t\tassertEquals(2, list.size());\n\t}\n\n\tstatic Stream stringIntAndListProvider() {\n\t\treturn Stream.of(\n\t\t\targuments(\"apple\", 1, Arrays.asList(\"a\", \"b\")),\n\t\t\targuments(\"lemon\", 2, Arrays.asList(\"x\", \"y\"))\n\t\t);\n\t}\n\t// end::multi_arg_MethodSource_example[]\n\t// @formatter:on\n\n\t// @formatter:off\n\t// tag::default_field_FieldSource_example[]\n\t@ParameterizedTest\n\t@FieldSource\n\tvoid arrayOfFruits(String fruit) {\n\t\tassertFruit(fruit);\n\t}\n\n\tstatic final String[] arrayOfFruits = { \"apple\", \"banana\" };\n\t// end::default_field_FieldSource_example[]\n\t// @formatter:on\n\n\t// @formatter:off\n\t// tag::explicit_field_FieldSource_example[]\n\t@ParameterizedTest\n\t@FieldSource(\"listOfFruits\")\n\tvoid singleFieldSource(String fruit) {\n\t\tassertFruit(fruit);\n\t}\n\n\tstatic final List listOfFruits = Arrays.asList(\"apple\", \"banana\");\n\t// end::explicit_field_FieldSource_example[]\n\t// @formatter:on\n\n\t// @formatter:off\n\t// tag::multiple_fields_FieldSource_example[]\n\t@ParameterizedTest\n\t@FieldSource({ \"listOfFruits\", \"additionalFruits\" })\n\tvoid multipleFieldSources(String fruit) {\n\t\tassertFruit(fruit);\n\t}\n\n\tstatic final Collection additionalFruits = Arrays.asList(\"cherry\", \"dewberry\");\n\t// end::multiple_fields_FieldSource_example[]\n\t// @formatter:on\n\n\t// @formatter:off\n\t// tag::named_arguments_FieldSource_example[]\n\t@ParameterizedTest\n\t@FieldSource\n\tvoid namedArgumentsSupplier(String fruit) {\n\t\tassertFruit(fruit);\n\t}\n\n\tstatic final Supplier> namedArgumentsSupplier = () -> Stream.of(\n\t\targuments(named(\"Apple\", \"apple\")),\n\t\targuments(named(\"Banana\", \"banana\"))\n\t);\n\t// end::named_arguments_FieldSource_example[]\n\t// @formatter:on\n\n\tprivate static void assertFruit(String fruit) {\n\t\tassertTrue(Arrays.asList(\"apple\", \"banana\", \"cherry\", \"dewberry\").contains(fruit));\n\t}\n\n\t// @formatter:off\n\t// tag::multi_arg_FieldSource_example[]\n\t@ParameterizedTest\n\t@FieldSource(\"stringIntAndListArguments\")\n\tvoid testWithMultiArgFieldSource(String str, int num, List list) {\n\t\tassertEquals(5, str.length());\n\t\tassertTrue(num >=1 && num <=2);\n\t\tassertEquals(2, list.size());\n\t}\n\n\tstatic List stringIntAndListArguments = Arrays.asList(\n\t\targuments(\"apple\", 1, Arrays.asList(\"a\", \"b\")),\n\t\targuments(\"lemon\", 2, Arrays.asList(\"x\", \"y\"))\n\t);\n\t// end::multi_arg_FieldSource_example[]\n\t// @formatter:on\n\n\t// @formatter:off\n\t// tag::CsvSource_example[]\n\t@ParameterizedTest\n\t@CsvSource({\n\t\t\"apple, 1\",\n\t\t\"banana, 2\",\n\t\t\"'lemon, lime', 0xF1\",\n\t\t\"strawberry, 700_000\"\n\t})\n\tvoid testWithCsvSource(String fruit, int rank) {\n\t\tassertNotNull(fruit);\n\t\tassertNotEquals(0, rank);\n\t}\n\t// end::CsvSource_example[]\n\t// @formatter:on\n\n\t// tag::CsvFileSource_example[]\n\t@ParameterizedTest\n\t@CsvFileSource(resources = \"/two-column.csv\", numLinesToSkip = 1)\n\tvoid testWithCsvFileSourceFromClasspath(String country, int reference) {\n\t\tassertNotNull(country);\n\t\tassertNotEquals(0, reference);\n\t}\n\n\t@ParameterizedTest\n\t@CsvFileSource(files = \"src/test/resources/two-column.csv\", numLinesToSkip = 1)\n\tvoid testWithCsvFileSourceFromFile(String country, int reference) {\n\t\tassertNotNull(country);\n\t\tassertNotEquals(0, reference);\n\t}\n\n\t@ParameterizedTest\n\t@CsvFileSource(resources = \"/two-column.csv\", useHeadersInDisplayName = true)\n\tvoid testWithCsvFileSourceAndHeaders(String country, int reference) {\n\t\tassertNotNull(country);\n\t\tassertNotEquals(0, reference);\n\t}\n\t// end::CsvFileSource_example[]\n\n\t// tag::ArgumentsSource_example[]\n\t@ParameterizedTest\n\t@ArgumentsSource(MyArgumentsProvider.class)\n\tvoid testWithArgumentsSource(String argument) {\n\t\tassertNotNull(argument);\n\t}\n\n\t// end::ArgumentsSource_example[]\n\tstatic\n\t// tag::ArgumentsProvider_example[]\n\tpublic class MyArgumentsProvider implements ArgumentsProvider {\n\n\t\t@Override\n\t\tpublic Stream provideArguments(ParameterDeclarations parameters,\n\t\t\t\tExtensionContext context) {\n\t\t\treturn Stream.of(\"apple\", \"banana\").map(Arguments::of);\n\t\t}\n\t}\n\t// end::ArgumentsProvider_example[]\n\n\t@ParameterizedTest\n\t@ArgumentsSource(MyArgumentsProviderWithConstructorInjection.class)\n\tvoid testWithArgumentsSourceWithConstructorInjection(String argument) {\n\t\tassertNotNull(argument);\n\t}\n\n\tstatic\n\t// tag::ArgumentsProviderWithConstructorInjection_example[]\n\tpublic class MyArgumentsProviderWithConstructorInjection implements ArgumentsProvider {\n\n\t\tprivate final TestInfo testInfo;\n\n\t\t// end::ArgumentsProviderWithConstructorInjection_example[]\n\t\t@SuppressWarnings(\"RedundantModifier\")\n\t\t// tag::ArgumentsProviderWithConstructorInjection_example[]\n\t\tpublic MyArgumentsProviderWithConstructorInjection(TestInfo testInfo) {\n\t\t\tthis.testInfo = testInfo;\n\t\t}\n\n\t\t@Override\n\t\tpublic Stream provideArguments(ParameterDeclarations parameters,\n\t\t\t\tExtensionContext context) {\n\t\t\treturn Stream.of(Arguments.of(testInfo.getDisplayName()));\n\t\t}\n\t}\n\t// end::ArgumentsProviderWithConstructorInjection_example[]\n\n\t// tag::ParameterResolver_example[]\n\t@BeforeEach\n\tvoid beforeEach(TestInfo testInfo) {\n\t\t// ...\n\t}\n\n\t@ParameterizedTest\n\t@ValueSource(strings = \"apple\")\n\tvoid testWithRegularParameterResolver(String argument, TestReporter testReporter) {\n\t\ttestReporter.publishEntry(\"argument\", argument);\n\t}\n\n\t@AfterEach\n\tvoid afterEach(TestInfo testInfo) {\n\t\t// ...\n\t}\n\t// end::ParameterResolver_example[]\n\n\t// tag::implicit_conversion_example[]\n\t@ParameterizedTest\n\t@ValueSource(strings = \"SECONDS\")\n\tvoid testWithImplicitArgumentConversion(ChronoUnit argument) {\n\t\tassertNotNull(argument.name());\n\t}\n\t// end::implicit_conversion_example[]\n\n\t// tag::implicit_fallback_conversion_example[]\n\t@ParameterizedTest\n\t@ValueSource(strings = \"42 Cats\")\n\tvoid testWithImplicitFallbackArgumentConversion(Book book) {\n\t\tassertEquals(\"42 Cats\", book.getTitle());\n\t}\n\n\t// end::implicit_fallback_conversion_example[]\n\tstatic\n\t// tag::implicit_fallback_conversion_example_Book[]\n\tpublic class Book {\n\n\t\tprivate final String title;\n\n\t\tprivate Book(String title) {\n\t\t\tthis.title = title;\n\t\t}\n\n\t\tpublic static Book fromTitle(String title) {\n\t\t\treturn new Book(title);\n\t\t}\n\n\t\tpublic String getTitle() {\n\t\t\treturn this.title;\n\t\t}\n\t}\n\t// end::implicit_fallback_conversion_example_Book[]\n\n\t// @formatter:off\n\t// tag::explicit_conversion_example[]\n\t@ParameterizedTest\n\t@EnumSource(ChronoUnit.class)\n\tvoid testWithExplicitArgumentConversion(\n\t\t\t@ConvertWith(ToStringArgumentConverter.class) String argument) {\n\n\t\tassertNotNull(ChronoUnit.valueOf(argument));\n\t}\n\n\t// end::explicit_conversion_example[]\n\tstatic\n\t@SuppressWarnings({ \"NullableProblems\", \"NullAway\" })\n\t// tag::explicit_conversion_example_ToStringArgumentConverter[]\n\tpublic class ToStringArgumentConverter extends SimpleArgumentConverter {\n\n\t\t@Override\n\t\tprotected Object convert(Object source, Class targetType) {\n\t\t\tassertEquals(String.class, targetType, \"Can only convert to String\");\n\t\t\tif (source instanceof Enum constant) {\n\t\t\t\treturn constant.name();\n\t\t\t}\n\t\t\treturn String.valueOf(source);\n\t\t}\n\t}\n\t// end::explicit_conversion_example_ToStringArgumentConverter[]\n\n\tstatic\n\t@SuppressWarnings({ \"NullableProblems\", \"NullAway\", \"ConstantValue\" })\n\t// tag::explicit_conversion_example_TypedArgumentConverter[]\n\tpublic class ToLengthArgumentConverter extends TypedArgumentConverter {\n\n\t\tprotected ToLengthArgumentConverter() {\n\t\t\tsuper(String.class, Integer.class);\n\t\t}\n\n\t\t@Override\n\t\tprotected Integer convert(String source) {\n\t\t\treturn (source != null ? source.length() : 0);\n\t\t}\n\n\t}\n\t// end::explicit_conversion_example_TypedArgumentConverter[]\n\n\t// tag::explicit_java_time_converter[]\n\t@ParameterizedTest\n\t@ValueSource(strings = { \"01.01.2017\", \"31.12.2017\" })\n\tvoid testWithExplicitJavaTimeConverter(\n\t\t\t@JavaTimeConversionPattern(\"dd.MM.yyyy\") LocalDate argument) {\n\n\t\tassertEquals(2017, argument.getYear());\n\t}\n\t// end::explicit_java_time_converter[]\n\t// @formatter:on\n\n\t// @formatter:off\n\t// tag::ArgumentsAccessor_example[]\n\t@ParameterizedTest\n\t@CsvSource({\n\t\t\"Jane, Doe, F, 1990-05-20\",\n\t\t\"John, Doe, M, 1990-10-22\"\n\t})\n\tvoid testWithArgumentsAccessor(ArgumentsAccessor arguments) {\n\t\tPerson person = new Person(\n\t\t\t\t\t\t\t\t\targuments.getString(0),\n\t\t\t\t\t\t\t\t\targuments.getString(1),\n\t\t\t\t\t\t\t\t\targuments.get(2, Gender.class),\n\t\t\t\t\t\t\t\t\targuments.get(3, LocalDate.class));\n\n\t\tif (person.getFirstName().equals(\"Jane\")) {\n\t\t\tassertEquals(Gender.F, person.getGender());\n\t\t}\n\t\telse {\n\t\t\tassertEquals(Gender.M, person.getGender());\n\t\t}\n\t\tassertEquals(\"Doe\", person.getLastName());\n\t\tassertEquals(1990, person.getDateOfBirth().getYear());\n\t}\n\t// end::ArgumentsAccessor_example[]\n\t// @formatter:on\n\n\t// @formatter:off\n\t// tag::ArgumentsAggregator_example[]\n\t@ParameterizedTest\n\t@CsvSource({\n\t\t\"Jane, Doe, F, 1990-05-20\",\n\t\t\"John, Doe, M, 1990-10-22\"\n\t})\n\tvoid testWithArgumentsAggregator(@AggregateWith(PersonAggregator.class) Person person) {\n\t\t// perform assertions against person\n\t}\n\n\t// end::ArgumentsAggregator_example[]\n\tstatic\n\t// tag::ArgumentsAggregator_example_PersonAggregator[]\n\tpublic class PersonAggregator extends SimpleArgumentsAggregator {\n\t\t@Override\n\t\tprotected Person aggregateArguments(ArgumentsAccessor arguments, Class targetType,\n\t\t\t\tAnnotatedElementContext context, int parameterIndex) {\n\t\t\treturn new Person(\n\t\t\t\t\t\t\t\targuments.getString(0),\n\t\t\t\t\t\t\t\targuments.getString(1),\n\t\t\t\t\t\t\t\targuments.get(2, Gender.class),\n\t\t\t\t\t\t\t\targuments.get(3, LocalDate.class));\n\t\t}\n\t}\n\t// end::ArgumentsAggregator_example_PersonAggregator[]\n\t// @formatter:on\n\n\t// @formatter:off\n\t// tag::ArgumentsAggregator_with_custom_annotation_example[]\n\t@ParameterizedTest\n\t@CsvSource({\n\t\t\"Jane, Doe, F, 1990-05-20\",\n\t\t\"John, Doe, M, 1990-10-22\"\n\t})\n\tvoid testWithCustomAggregatorAnnotation(@CsvToPerson Person person) {\n\t\t// perform assertions against person\n\t}\n\t// end::ArgumentsAggregator_with_custom_annotation_example[]\n\n\t// tag::ArgumentsAggregator_with_custom_annotation_example_CsvToPerson[]\n\t@Retention(RetentionPolicy.RUNTIME)\n\t@Target(ElementType.PARAMETER)\n\t@AggregateWith(PersonAggregator.class)\n\tpublic @interface CsvToPerson {\n\t}\n\t// end::ArgumentsAggregator_with_custom_annotation_example_CsvToPerson[]\n\t// @formatter:on\n\n\t// tag::custom_display_names[]\n\t@DisplayName(\"Display name of container\")\n\t@ParameterizedTest(name = \"{index} ==> the rank of {0} is {1}\")\n\t@CsvSource({ \"apple, 1\", \"banana, 2\", \"'lemon, lime', 3\" })\n\tvoid testWithCustomDisplayNames(String fruit, int rank) {\n\t}\n\t// end::custom_display_names[]\n\n\t// @formatter:off\n\t// tag::named_arguments[]\n\t@DisplayName(\"A parameterized test with named arguments\")\n\t@ParameterizedTest(name = \"{index}: {0}\")\n\t@MethodSource(\"namedArguments\")\n\tvoid testWithNamedArguments(File file) {\n\t}\n\n\tstatic Stream namedArguments() {\n\t\treturn Stream.of(\n\t\t\targuments(named(\"An important file\", new File(\"path1\"))),\n\t\t\targuments(named(\"Another file\", new File(\"path2\")))\n\t\t);\n\t}\n\t// end::named_arguments[]\n\t// @formatter:on\n\n\t// @formatter:off\n\t// tag::named_argument_set[]\n\t@DisplayName(\"A parameterized test with named argument sets\")\n\t@ParameterizedTest\n\t@FieldSource(\"argumentSets\")\n\tvoid testWithArgumentSets(File file1, File file2) {\n\t}\n\n\tstatic List argumentSets = Arrays.asList(\n\t\targumentSet(\"Important files\", new File(\"path1\"), new File(\"path2\")),\n\t\targumentSet(\"Other files\", new File(\"path3\"), new File(\"path4\"))\n\t);\n\t// end::named_argument_set[]\n\t// @formatter:on\n\n\t// tag::repeatable_annotations[]\n\t@DisplayName(\"A parameterized test that makes use of repeatable annotations\")\n\t@ParameterizedTest\n\t@MethodSource(\"someProvider\")\n\t@MethodSource(\"otherProvider\")\n\tvoid testWithRepeatedAnnotation(String argument) {\n\t\tassertNotNull(argument);\n\t}\n\n\tstatic Stream someProvider() {\n\t\treturn Stream.of(\"foo\");\n\t}\n\n\tstatic Stream otherProvider() {\n\t\treturn Stream.of(\"bar\");\n\t}\n\t// end::repeatable_annotations[]\n\n\t@Disabled(\"Fails prior to invoking the test method\")\n\t// tag::argument_count_validation[]\n\t@ParameterizedTest(argumentCountValidation = ArgumentCountValidationMode.STRICT)\n\t@CsvSource({ \"42, -666\" })\n\tvoid testWithArgumentCountValidation(int number) {\n\t\tassertTrue(number > 0);\n\t}\n\t// end::argument_count_validation[]\n}\n"
},
{
"path": "documentation/src/test/java/example/PollingTimeoutDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.Timeout;\n\nclass PollingTimeoutDemo {\n\n\t// tag::user_guide[]\n\t@Test\n\t@Timeout(5) // Poll at most 5 seconds\n\tvoid pollUntil() throws InterruptedException {\n\t\twhile (asynchronousResultNotAvailable()) {\n\t\t\tThread.sleep(250); // custom poll interval\n\t\t}\n\t\t// Obtain the asynchronous result and perform assertions\n\t}\n\t// end::user_guide[]\n\n\tprivate boolean asynchronousResultNotAvailable() {\n\t\treturn false;\n\t}\n\n}\n"
},
{
"path": "documentation/src/test/java/example/RepeatedTestsDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\n// tag::user_guide[]\nimport static org.junit.jupiter.api.Assertions.assertEquals;\nimport static org.junit.jupiter.api.Assertions.fail;\n\nimport java.util.logging.Logger;\n\nimport org.junit.jupiter.api.BeforeEach;\nimport org.junit.jupiter.api.DisplayName;\nimport org.junit.jupiter.api.RepeatedTest;\nimport org.junit.jupiter.api.RepetitionInfo;\nimport org.junit.jupiter.api.TestInfo;\n\n// end::user_guide[]\n// Use fully qualified names to avoid having them show up in the imports.\n@org.junit.jupiter.api.parallel.Execution(org.junit.jupiter.api.parallel.ExecutionMode.SAME_THREAD)\n// tag::user_guide[]\nclass RepeatedTestsDemo {\n\n\tprivate Logger logger = // ...\n\t\t// end::user_guide[]\n\t\tLogger.getLogger(RepeatedTestsDemo.class.getName());\n\t// tag::user_guide[]\n\n\t@BeforeEach\n\tvoid beforeEach(TestInfo testInfo, RepetitionInfo repetitionInfo) {\n\t\tint currentRepetition = repetitionInfo.getCurrentRepetition();\n\t\tint totalRepetitions = repetitionInfo.getTotalRepetitions();\n\t\tString methodName = testInfo.getTestMethod().get().getName();\n\t\tlogger.info(\"About to execute repetition %d of %d for %s\".formatted( //\n\t\t\tcurrentRepetition, totalRepetitions, methodName));\n\t}\n\n\t@RepeatedTest(10)\n\tvoid repeatedTest() {\n\t\t// ...\n\t}\n\n\t@RepeatedTest(5)\n\tvoid repeatedTestWithRepetitionInfo(RepetitionInfo repetitionInfo) {\n\t\tassertEquals(5, repetitionInfo.getTotalRepetitions());\n\t}\n\n\t// end::user_guide[]\n\t// Use fully qualified name to avoid having it show up in the imports.\n\t@org.junit.jupiter.api.Disabled(\"intentional failures would break the build\")\n\t// tag::user_guide[]\n\t@RepeatedTest(value = 8, failureThreshold = 2)\n\tvoid repeatedTestWithFailureThreshold(RepetitionInfo repetitionInfo) {\n\t\t// Simulate unexpected failure every second repetition\n\t\tif (repetitionInfo.getCurrentRepetition() % 2 == 0) {\n\t\t\tfail(\"Boom!\");\n\t\t}\n\t}\n\n\t@RepeatedTest(value = 1, name = \"{displayName} {currentRepetition}/{totalRepetitions}\")\n\t@DisplayName(\"Repeat!\")\n\tvoid customDisplayName(TestInfo testInfo) {\n\t\tassertEquals(\"Repeat! 1/1\", testInfo.getDisplayName());\n\t}\n\n\t@RepeatedTest(value = 1, name = RepeatedTest.LONG_DISPLAY_NAME)\n\t@DisplayName(\"Details...\")\n\tvoid customDisplayNameWithLongPattern(TestInfo testInfo) {\n\t\tassertEquals(\"Details... :: repetition 1 of 1\", testInfo.getDisplayName());\n\t}\n\n\t@RepeatedTest(value = 5, name = \"Wiederholung {currentRepetition} von {totalRepetitions}\")\n\tvoid repeatedTestInGerman() {\n\t\t// ...\n\t}\n\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/SecondCustomEngine.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\nimport static java.net.InetAddress.getLoopbackAddress;\nimport static org.junit.platform.engine.TestExecutionResult.successful;\n\nimport java.io.IOException;\nimport java.io.UncheckedIOException;\nimport java.net.ServerSocket;\n\nimport org.jspecify.annotations.Nullable;\nimport org.junit.platform.engine.EngineDiscoveryRequest;\nimport org.junit.platform.engine.ExecutionRequest;\nimport org.junit.platform.engine.TestDescriptor;\nimport org.junit.platform.engine.TestEngine;\nimport org.junit.platform.engine.UniqueId;\nimport org.junit.platform.engine.support.descriptor.EngineDescriptor;\nimport org.junit.platform.engine.support.store.Namespace;\nimport org.junit.platform.engine.support.store.NamespacedHierarchicalStore;\n\n//tag::user_guide[]\n/**\n * Second custom test engine implementation.\n */\npublic class SecondCustomEngine implements TestEngine {\n\n\t//end::user_guide[]\n\t@Nullable\n\t//tag::user_guide[]\n\tpublic ServerSocket socket;\n\n\t@Override\n\tpublic String getId() {\n\t\treturn \"second-custom-test-engine\";\n\t}\n\n\t//end::user_guide[]\n\t@Nullable\n\t//tag::user_guide[]\n\tpublic ServerSocket getSocket() {\n\t\treturn this.socket;\n\t}\n\n\t@Override\n\tpublic TestDescriptor discover(EngineDiscoveryRequest discoveryRequest, UniqueId uniqueId) {\n\t\treturn new EngineDescriptor(uniqueId, \"Second Custom Test Engine\");\n\t}\n\n\t@Override\n\tpublic void execute(ExecutionRequest request) {\n\t\trequest.getEngineExecutionListener()\n\t\t\t\t// tag::custom_line_break[]\n\t\t\t\t.executionStarted(request.getRootTestDescriptor());\n\n\t\tNamespacedHierarchicalStore store = request.getStore();\n\t\tsocket = store.computeIfAbsent(Namespace.GLOBAL, \"serverSocket\", key -> {\n\t\t\ttry {\n\t\t\t\treturn new ServerSocket(0, 50, getLoopbackAddress());\n\t\t\t}\n\t\t\tcatch (IOException e) {\n\t\t\t\tthrow new UncheckedIOException(\"Failed to start ServerSocket\", e);\n\t\t\t}\n\t\t}, ServerSocket.class);\n\n\t\trequest.getEngineExecutionListener()\n\t\t\t\t// tag::custom_line_break[]\n\t\t\t\t.executionFinished(request.getRootTestDescriptor(), successful());\n\t}\n\n}\n//end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/SlowTests.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\nimport static org.junit.jupiter.api.parallel.ExecutionMode.SAME_THREAD;\n\nimport java.util.stream.IntStream;\n\nimport org.junit.jupiter.api.Disabled;\nimport org.junit.jupiter.api.Tag;\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.parallel.Execution;\n\n@Tag(\"exclude\")\n@Disabled\nclass SlowTests {\n\n\t@Execution(SAME_THREAD)\n\t@Test\n\tvoid a() {\n\t\tfoo();\n\t}\n\n\t@Test\n\tvoid b() {\n\t\tfoo();\n\t}\n\n\t@Test\n\tvoid c() {\n\t\tfoo();\n\t}\n\n\t@Test\n\tvoid d() {\n\t\tfoo();\n\t}\n\n\t@Test\n\tvoid e() {\n\t\tfoo();\n\t}\n\n\t@Test\n\tvoid f() {\n\t\tfoo();\n\t}\n\n\t@Test\n\tvoid g() {\n\t\tfoo();\n\t}\n\n\t@Test\n\tvoid h() {\n\t\tfoo();\n\t}\n\n\t@Test\n\tvoid i() {\n\t\tfoo();\n\t}\n\n\t@Test\n\tvoid j() {\n\t\tfoo();\n\t}\n\n\t@Test\n\tvoid k() {\n\t\tfoo();\n\t}\n\n\t@Test\n\tvoid l() {\n\t\tfoo();\n\t}\n\n\t@Test\n\tvoid m() {\n\t\tfoo();\n\t}\n\n\t@Test\n\tvoid n() {\n\t\tfoo();\n\t}\n\n\t@Test\n\tvoid o() {\n\t\tfoo();\n\t}\n\n\t@Test\n\tvoid p() {\n\t\tfoo();\n\t}\n\n\t@Execution(SAME_THREAD)\n\t@Test\n\tvoid q() {\n\t\tfoo();\n\t}\n\n\t@Test\n\tvoid r() {\n\t\tfoo();\n\t}\n\n\t@Test\n\tvoid s() {\n\t\tfoo();\n\t}\n\n\tprivate void foo() {\n\t\tIntStream.range(1, 100_000_000).mapToDouble(i -> Math.pow(i, i)).map(Math::sqrt).max();\n\t}\n}\n"
},
{
"path": "documentation/src/test/java/example/StandardTests.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\n// tag::user_guide[]\nimport static org.junit.jupiter.api.Assertions.fail;\nimport static org.junit.jupiter.api.Assumptions.assumeTrue;\n\nimport org.junit.jupiter.api.AfterAll;\nimport org.junit.jupiter.api.AfterEach;\nimport org.junit.jupiter.api.BeforeAll;\nimport org.junit.jupiter.api.BeforeEach;\nimport org.junit.jupiter.api.Disabled;\nimport org.junit.jupiter.api.Test;\n\nclass StandardTests {\n\n\t@BeforeAll\n\tstatic void initAll() {\n\t}\n\n\t@BeforeEach\n\tvoid init() {\n\t}\n\n\t@Test\n\tvoid succeedingTest() {\n\t}\n\n\t// end::user_guide[]\n\t@extensions.ExpectToFail\n\t// tag::user_guide[]\n\t@Test\n\tvoid failingTest() {\n\t\tfail(\"a failing test\");\n\t}\n\n\t@Test\n\t@Disabled(\"for demonstration purposes\")\n\tvoid skippedTest() {\n\t\t// not executed\n\t}\n\n\t@Test\n\tvoid abortedTest() {\n\t\tassumeTrue(\"abc\".contains(\"Z\"));\n\t\tfail(\"test should have been aborted\");\n\t}\n\n\t@AfterEach\n\tvoid tearDown() {\n\t}\n\n\t@AfterAll\n\tstatic void tearDownAll() {\n\t}\n\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/SuiteDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\n//tag::user_guide[]\nimport org.junit.platform.suite.api.IncludeClassNamePatterns;\nimport org.junit.platform.suite.api.SelectPackages;\nimport org.junit.platform.suite.api.Suite;\nimport org.junit.platform.suite.api.SuiteDisplayName;\n\n@Suite\n@SuiteDisplayName(\"JUnit Platform Suite Demo\")\n@SelectPackages(\"example\")\n@IncludeClassNamePatterns(\".*Tests\")\n//end::user_guide[]\n@org.junit.platform.suite.api.ExcludeTags(\"exclude\")\n//tag::user_guide[]\nclass SuiteDemo {\n}\n//end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/SystemPropertyExtensionDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\nimport static org.assertj.core.api.Assertions.assertThat;\n\nimport org.junit.jupiter.api.BeforeAll;\nimport org.junit.jupiter.api.BeforeEach;\nimport org.junit.jupiter.api.ClassOrderer;\nimport org.junit.jupiter.api.Nested;\nimport org.junit.jupiter.api.Order;\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.TestClassOrder;\nimport org.junit.jupiter.api.TestInstance;\nimport org.junit.jupiter.api.util.ClearSystemProperty;\nimport org.junit.jupiter.api.util.ReadsSystemProperty;\nimport org.junit.jupiter.api.util.RestoreSystemProperties;\nimport org.junit.jupiter.api.util.SetSystemProperty;\nimport org.junit.jupiter.params.ParameterizedTest;\nimport org.junit.jupiter.params.provider.ValueSource;\n\npublic class SystemPropertyExtensionDemo {\n\n\t// tag::systemproperty_clear_simple[]\n\t@Test\n\t@ClearSystemProperty(key = \"some property\")\n\tvoid testClearingProperty() {\n\t\tassertThat(System.getProperty(\"some property\")).isNull();\n\t}\n\t// end::systemproperty_clear_simple[]\n\n\t// tag::systemproperty_set_simple[]\n\t@Test\n\t@SetSystemProperty(key = \"some property\", value = \"new value\")\n\tvoid testSettingProperty() {\n\t\tassertThat(System.getProperty(\"some property\")).isEqualTo(\"new value\");\n\t}\n\t// end::systemproperty_set_simple[]\n\n\t// tag::systemproperty_using_set_and_clear[]\n\t@Test\n\t@ClearSystemProperty(key = \"1st property\")\n\t@ClearSystemProperty(key = \"2nd property\")\n\t@SetSystemProperty(key = \"3rd property\", value = \"new value\")\n\tvoid testClearingAndSettingProperty() {\n\t\tassertThat(System.getProperty(\"1st property\")).isNull();\n\t\tassertThat(System.getProperty(\"2nd property\")).isNull();\n\t\tassertThat(System.getProperty(\"3rd property\")).isEqualTo(\"new value\");\n\t}\n\t// end::systemproperty_using_set_and_clear[]\n\n\t@Nested\n\t// tag::systemproperty_using_at_class_level[]\n\t@ClearSystemProperty(key = \"some property\")\n\tclass MySystemPropertyTest {\n\n\t\t@Test\n\t\t@SetSystemProperty(key = \"some property\", value = \"new value\")\n\t\tvoid clearedAtClasslevel() {\n\t\t\tassertThat(System.getProperty(\"some property\")).isEqualTo(\"new value\");\n\t\t}\n\n\t}\n\t// end::systemproperty_using_at_class_level[]\n\n\t// tag::systemproperty_restore_test[]\n\t@ParameterizedTest\n\t@ValueSource(strings = { \"foo\", \"bar\" })\n\t@RestoreSystemProperties\n\tvoid parameterizedTest(String value) {\n\t\tSystem.setProperty(\"some parameterized property\", value);\n\t\tSystem.setProperty(\"some other dynamic property\", \"my code calculates somehow\");\n\t}\n\t// end::systemproperty_restore_test[]\n\n\t@Nested\n\t@TestClassOrder(ClassOrderer.OrderAnnotation.class)\n\tclass SystemPropertyRestoreExample {\n\n\t\t@Nested\n\t\t@Order(1)\n\t\t// tag::systemproperty_class_restore_setup[]\n\t\t@TestInstance(TestInstance.Lifecycle.PER_CLASS)\n\t\t@RestoreSystemProperties\n\t\tclass MySystemPropertyRestoreTest {\n\n\t\t\t@BeforeAll\n\t\t\tvoid beforeAll() {\n\t\t\t\tSystem.setProperty(\"A\", \"A value\");\n\t\t\t}\n\n\t\t\t@BeforeEach\n\t\t\tvoid beforeEach() {\n\t\t\t\tSystem.setProperty(\"B\", \"B value\");\n\t\t\t}\n\n\t\t\t@Test\n\t\t\tvoid isolatedTest1() {\n\t\t\t\tSystem.setProperty(\"C\", \"C value\");\n\t\t\t}\n\n\t\t\t@Test\n\t\t\tvoid isolatedTest2() {\n\t\t\t\tassertThat(System.getProperty(\"A\")).isEqualTo(\"A value\");\n\t\t\t\tassertThat(System.getProperty(\"B\")).isEqualTo(\"B value\");\n\n\t\t\t\t// Class-level @RestoreSystemProperties restores \"C\" to original state\n\t\t\t\tassertThat(System.getProperty(\"C\")).isNull();\n\t\t\t}\n\n\t\t}\n\t\t// end::systemproperty_class_restore_setup[]\n\n\t\t@Nested\n\t\t@Order(2)\n\t\t// tag::systemproperty_class_restore_isolated_class[]\n\t\t@ReadsSystemProperty\n\t\tclass SomeOtherTestClass {\n\n\t\t\t@Test\n\t\t\tvoid isolatedTest() {\n\t\t\t\tassertThat(System.getProperty(\"A\")).isNull();\n\t\t\t\tassertThat(System.getProperty(\"B\")).isNull();\n\t\t\t\tassertThat(System.getProperty(\"C\")).isNull();\n\t\t\t}\n\n\t\t}\n\t\t// end::systemproperty_class_restore_isolated_class[]\n\t}\n\n\t// tag::systemproperty_method_combine_all_test[]\n\t@ParameterizedTest\n\t@ValueSource(ints = { 100, 500, 1000 })\n\t@RestoreSystemProperties\n\t@SetSystemProperty(key = \"DISABLE_CACHE\", value = \"TRUE\")\n\t@ClearSystemProperty(key = \"COPYWRITE_OVERLAY_TEXT\")\n\tvoid imageGenerationTest(int imageSize) {\n\t\tSystem.setProperty(\"IMAGE_SIZE\", String.valueOf(imageSize)); // Requires restore\n\n\t\t// Test your image generation utility with the current system properties\n\t}\n\t// end::systemproperty_method_combine_all_test[]\n\n}\n"
},
{
"path": "documentation/src/test/java/example/TaggingDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\n// tag::user_guide[]\nimport org.junit.jupiter.api.Tag;\nimport org.junit.jupiter.api.Test;\n\n@Tag(\"fast\")\n@Tag(\"model\")\nclass TaggingDemo {\n\n\t@Test\n\t@Tag(\"taxes\")\n\tvoid testingTaxCalculation() {\n\t}\n\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/TempDirectoryDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\nimport static org.junit.jupiter.api.Assertions.assertEquals;\nimport static org.junit.jupiter.api.Assertions.assertNotEquals;\nimport static org.junit.jupiter.api.Assertions.assertTrue;\nimport static org.junit.jupiter.api.io.CleanupMode.ON_SUCCESS;\n\nimport java.io.IOException;\nimport java.lang.annotation.ElementType;\nimport java.lang.annotation.Retention;\nimport java.lang.annotation.RetentionPolicy;\nimport java.lang.annotation.Target;\nimport java.nio.file.FileSystem;\nimport java.nio.file.Files;\nimport java.nio.file.Path;\nimport java.util.List;\n\nimport com.google.common.jimfs.Configuration;\nimport com.google.common.jimfs.Jimfs;\n\nimport example.TempDirectoryDemo.InMemoryTempDirDemo.JimfsTempDirFactory;\nimport example.util.ListWriter;\n\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.extension.AnnotatedElementContext;\nimport org.junit.jupiter.api.extension.ExtensionContext;\nimport org.junit.jupiter.api.io.TempDir;\nimport org.junit.jupiter.api.io.TempDirDeletionStrategy;\nimport org.junit.jupiter.api.io.TempDirFactory;\n\n@SuppressWarnings(\"NewClassNamingConvention\")\nclass TempDirectoryDemo {\n\n\t// tag::user_guide_parameter_injection[]\n\t@Test\n\tvoid writeItemsToFile(@TempDir Path tempDir) throws IOException {\n\t\tPath file = tempDir.resolve(\"test.txt\");\n\n\t\tnew ListWriter(file).write(\"a\", \"b\", \"c\");\n\n\t\tassertEquals(List.of(\"a,b,c\"), Files.readAllLines(file));\n\t}\n\t// end::user_guide_parameter_injection[]\n\n\t// tag::user_guide_multiple_directories[]\n\t@Test\n\tvoid copyFileFromSourceToTarget(@TempDir Path source, @TempDir Path target) throws IOException {\n\t\tPath sourceFile = source.resolve(\"test.txt\");\n\t\tnew ListWriter(sourceFile).write(\"a\", \"b\", \"c\");\n\n\t\tPath targetFile = Files.copy(sourceFile, target.resolve(\"test.txt\"));\n\n\t\tassertNotEquals(sourceFile, targetFile);\n\t\tassertEquals(List.of(\"a,b,c\"), Files.readAllLines(targetFile));\n\t}\n\t// end::user_guide_multiple_directories[]\n\n\tstatic\n\t// tag::user_guide_field_injection[]\n\tclass SharedTempDirectoryDemo {\n\n\t\t@TempDir\n\t\tstatic Path sharedTempDir;\n\n\t\t@Test\n\t\tvoid writeItemsToFile() throws IOException {\n\t\t\tPath file = sharedTempDir.resolve(\"test.txt\");\n\n\t\t\tnew ListWriter(file).write(\"a\", \"b\", \"c\");\n\n\t\t\tassertEquals(List.of(\"a,b,c\"), Files.readAllLines(file));\n\t\t}\n\n\t\t@Test\n\t\tvoid anotherTestThatUsesTheSameTempDir() {\n\t\t\t// use sharedTempDir\n\t\t}\n\n\t}\n\t// end::user_guide_field_injection[]\n\n\tstatic\n\t// tag::user_guide_cleanup_mode[]\n\tclass CleanupModeDemo {\n\n\t\t@Test\n\t\tvoid fileTest(@TempDir(cleanup = ON_SUCCESS) Path tempDir) {\n\t\t\t// perform test\n\t\t}\n\n\t}\n\t// end::user_guide_cleanup_mode[]\n\n\tstatic\n\t// tag::user_guide_factory_name_prefix[]\n\tclass TempDirFactoryDemo {\n\n\t\t@Test\n\t\tvoid factoryTest(@TempDir(factory = Factory.class) Path tempDir) {\n\t\t\tassertTrue(tempDir.getFileName().toString().startsWith(\"factoryTest\"));\n\t\t}\n\n\t\tstatic class Factory implements TempDirFactory {\n\n\t\t\t@Override\n\t\t\tpublic Path createTempDirectory(AnnotatedElementContext elementContext, ExtensionContext extensionContext)\n\t\t\t\t\tthrows IOException {\n\t\t\t\treturn Files.createTempDirectory(extensionContext.getRequiredTestMethod().getName());\n\t\t\t}\n\n\t\t}\n\n\t}\n\t// end::user_guide_factory_name_prefix[]\n\n\tstatic\n\t// tag::user_guide_factory_jimfs[]\n\tclass InMemoryTempDirDemo {\n\n\t\t@Test\n\t\tvoid test(@TempDir(factory = JimfsTempDirFactory.class) Path tempDir) {\n\t\t\t// perform test\n\t\t}\n\n\t\tstatic class JimfsTempDirFactory implements TempDirFactory {\n\n\t\t\tprivate final FileSystem fileSystem = Jimfs.newFileSystem(Configuration.unix());\n\n\t\t\t@Override\n\t\t\tpublic Path createTempDirectory(AnnotatedElementContext elementContext, ExtensionContext extensionContext)\n\t\t\t\t\tthrows IOException {\n\t\t\t\treturn Files.createTempDirectory(fileSystem.getPath(\"/\"), \"junit-\");\n\t\t\t}\n\n\t\t\t@Override\n\t\t\tpublic void close() throws IOException {\n\t\t\t\tfileSystem.close();\n\t\t\t}\n\n\t\t}\n\n\t}\n\t// end::user_guide_factory_jimfs[]\n\n\tstatic\n\t// tag::user_guide_deletion_strategy[]\n\tclass DeletionStrategyDemo {\n\n\t\t@Test\n\t\tvoid test(@TempDir(deletionStrategy = TempDirDeletionStrategy.IgnoreFailures.class) Path tempDir) {\n\t\t\t// perform test\n\t\t}\n\n\t}\n\t// end::user_guide_deletion_strategy[]\n\n\t// tag::user_guide_composed_annotation[]\n\t@Target({ ElementType.ANNOTATION_TYPE, ElementType.FIELD, ElementType.PARAMETER })\n\t@Retention(RetentionPolicy.RUNTIME)\n\t@TempDir(factory = JimfsTempDirFactory.class)\n\t@interface JimfsTempDir {\n\t}\n\t// end::user_guide_composed_annotation[]\n\n\tstatic\n\t// tag::user_guide_composed_annotation_usage[]\n\tclass JimfsTempDirAnnotationDemo {\n\n\t\t@Test\n\t\tvoid test(@JimfsTempDir Path tempDir) {\n\t\t\t// perform test\n\t\t}\n\n\t}\n\t// end::user_guide_composed_annotation_usage[]\n\n}\n"
},
{
"path": "documentation/src/test/java/example/TestInfoDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\n// tag::user_guide[]\nimport static org.junit.jupiter.api.Assertions.assertEquals;\nimport static org.junit.jupiter.api.Assertions.assertTrue;\n\nimport org.junit.jupiter.api.BeforeAll;\nimport org.junit.jupiter.api.BeforeEach;\nimport org.junit.jupiter.api.DisplayName;\nimport org.junit.jupiter.api.Tag;\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.TestInfo;\n\n@DisplayName(\"TestInfo Demo\")\nclass TestInfoDemo {\n\n\t@BeforeAll\n\tstatic void beforeAll(TestInfo testInfo) {\n\t\tassertEquals(\"TestInfo Demo\", testInfo.getDisplayName());\n\t}\n\n\tTestInfoDemo(TestInfo testInfo) {\n\t\tString displayName = testInfo.getDisplayName();\n\t\tassertTrue(displayName.equals(\"TEST 1\") || displayName.equals(\"test2()\"));\n\t}\n\n\t@BeforeEach\n\tvoid init(TestInfo testInfo) {\n\t\tString displayName = testInfo.getDisplayName();\n\t\tassertTrue(displayName.equals(\"TEST 1\") || displayName.equals(\"test2()\"));\n\t}\n\n\t@Test\n\t@DisplayName(\"TEST 1\")\n\t@Tag(\"my-tag\")\n\tvoid test1(TestInfo testInfo) {\n\t\tassertEquals(\"TEST 1\", testInfo.getDisplayName());\n\t\tassertTrue(testInfo.getTags().contains(\"my-tag\"));\n\t}\n\n\t@Test\n\tvoid test2() {\n\t}\n\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/TestReporterDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\nimport java.nio.file.Files;\nimport java.nio.file.Path;\nimport java.util.HashMap;\nimport java.util.List;\nimport java.util.Map;\n\nimport org.junit.jupiter.api.MediaType;\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.TestReporter;\nimport org.junit.jupiter.api.io.TempDir;\n\n// tag::user_guide[]\nclass TestReporterDemo {\n\n\t@Test\n\tvoid reportSingleValue(TestReporter testReporter) {\n\t\ttestReporter.publishEntry(\"a status message\");\n\t}\n\n\t@Test\n\tvoid reportKeyValuePair(TestReporter testReporter) {\n\t\ttestReporter.publishEntry(\"a key\", \"a value\");\n\t}\n\n\t@Test\n\tvoid reportMultipleKeyValuePairs(TestReporter testReporter) {\n\t\tMap values = new HashMap<>();\n\t\tvalues.put(\"user name\", \"dk38\");\n\t\tvalues.put(\"award year\", \"1974\");\n\n\t\ttestReporter.publishEntry(values);\n\t}\n\n\t@Test\n\tvoid reportFiles(TestReporter testReporter, @TempDir Path tempDir) throws Exception {\n\n\t\ttestReporter.publishFile(\"test1.txt\", MediaType.TEXT_PLAIN_UTF_8, file -> Files.write(file, List.of(\"Test 1\")));\n\n\t\tPath existingFile = Files.write(tempDir.resolve(\"test2.txt\"), List.of(\"Test 2\"));\n\t\ttestReporter.publishFile(existingFile, MediaType.TEXT_PLAIN_UTF_8);\n\n\t\ttestReporter.publishDirectory(\"test3\", dir -> {\n\t\t\tFiles.write(dir.resolve(\"nested1.txt\"), List.of(\"Nested content 1\"));\n\t\t\tFiles.write(dir.resolve(\"nested2.txt\"), List.of(\"Nested content 2\"));\n\t\t});\n\n\t\tPath existingDir = Files.createDirectory(tempDir.resolve(\"test4\"));\n\t\tFiles.write(existingDir.resolve(\"nested1.txt\"), List.of(\"Nested content 1\"));\n\t\tFiles.write(existingDir.resolve(\"nested2.txt\"), List.of(\"Nested content 2\"));\n\t\ttestReporter.publishDirectory(existingDir);\n\t}\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/TestTemplateDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\nimport static org.junit.jupiter.api.Assertions.assertTrue;\n\nimport java.util.Arrays;\nimport java.util.List;\nimport java.util.stream.Stream;\n\nimport org.junit.jupiter.api.TestTemplate;\nimport org.junit.jupiter.api.extension.ExtendWith;\nimport org.junit.jupiter.api.extension.Extension;\nimport org.junit.jupiter.api.extension.ExtensionContext;\nimport org.junit.jupiter.api.extension.ParameterContext;\nimport org.junit.jupiter.api.extension.ParameterResolver;\nimport org.junit.jupiter.api.extension.TestTemplateInvocationContext;\nimport org.junit.jupiter.api.extension.TestTemplateInvocationContextProvider;\n\nclass TestTemplateDemo {\n\n\t// tag::user_guide[]\n\tfinal List fruits = Arrays.asList(\"apple\", \"banana\", \"lemon\");\n\n\t@TestTemplate\n\t@ExtendWith(MyTestTemplateInvocationContextProvider.class)\n\tvoid testTemplate(String fruit) {\n\t\tassertTrue(fruits.contains(fruit));\n\t}\n\n\t// end::user_guide[]\n\tstatic\n\t// @formatter:off\n\t// tag::user_guide[]\n\tpublic class MyTestTemplateInvocationContextProvider\n\t\t\timplements TestTemplateInvocationContextProvider {\n\n\t\t@Override\n\t\tpublic boolean supportsTestTemplate(ExtensionContext context) {\n\t\t\treturn true;\n\t\t}\n\n\t\t@Override\n\t\tpublic Stream provideTestTemplateInvocationContexts(\n\t\t\t\tExtensionContext context) {\n\n\t\t\treturn Stream.of(invocationContext(\"apple\"), invocationContext(\"banana\"));\n\t\t}\n\n\t\tprivate TestTemplateInvocationContext invocationContext(String parameter) {\n\t\t\treturn new TestTemplateInvocationContext() {\n\t\t\t\t@Override\n\t\t\t\tpublic String getDisplayName(int invocationIndex) {\n\t\t\t\t\treturn parameter;\n\t\t\t\t}\n\n\t\t\t\t@Override\n\t\t\t\tpublic List getAdditionalExtensions() {\n\t\t\t\t\treturn List.of(new ParameterResolver() {\n\t\t\t\t\t\t@Override\n\t\t\t\t\t\tpublic boolean supportsParameter(ParameterContext parameterContext,\n\t\t\t\t\t\t\t\tExtensionContext extensionContext) {\n\t\t\t\t\t\t\treturn parameterContext.getParameter().getType().equals(String.class);\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\t@Override\n\t\t\t\t\t\tpublic Object resolveParameter(ParameterContext parameterContext,\n\t\t\t\t\t\t\t\tExtensionContext extensionContext) {\n\t\t\t\t\t\t\treturn parameter;\n\t\t\t\t\t\t}\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t};\n\t\t}\n\t}\n\t// end::user_guide[]\n\t// @formatter:on\n\n}\n"
},
{
"path": "documentation/src/test/java/example/TestingAStackDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\n// tag::user_guide[]\nimport static org.junit.jupiter.api.Assertions.assertEquals;\nimport static org.junit.jupiter.api.Assertions.assertFalse;\nimport static org.junit.jupiter.api.Assertions.assertThrows;\nimport static org.junit.jupiter.api.Assertions.assertTrue;\n\nimport java.util.EmptyStackException;\nimport java.util.Stack;\n\nimport org.junit.jupiter.api.BeforeEach;\nimport org.junit.jupiter.api.DisplayName;\nimport org.junit.jupiter.api.Nested;\nimport org.junit.jupiter.api.Test;\n\n@DisplayName(\"A stack\")\nclass TestingAStackDemo {\n\n\t@Test\n\t@DisplayName(\"is instantiated with new Stack()\")\n\tvoid isInstantiatedWithNew() {\n\t\tnew Stack<>();\n\t}\n\n\t@Nested\n\t@DisplayName(\"when new\")\n\tclass WhenNew {\n\n\t\tStack stack;\n\n\t\t@BeforeEach\n\t\tvoid createNewStack() {\n\t\t\tstack = new Stack<>();\n\t\t}\n\n\t\t@Test\n\t\t@DisplayName(\"is empty\")\n\t\tvoid isEmpty() {\n\t\t\tassertTrue(stack.isEmpty());\n\t\t}\n\n\t\t@Test\n\t\t@DisplayName(\"throws EmptyStackException when popped\")\n\t\tvoid throwsExceptionWhenPopped() {\n\t\t\tassertThrows(EmptyStackException.class, stack::pop);\n\t\t}\n\n\t\t@Test\n\t\t@DisplayName(\"throws EmptyStackException when peeked\")\n\t\tvoid throwsExceptionWhenPeeked() {\n\t\t\tassertThrows(EmptyStackException.class, stack::peek);\n\t\t}\n\n\t\t@Nested\n\t\t@DisplayName(\"after pushing an element\")\n\t\tclass AfterPushing {\n\n\t\t\tString anElement = \"an element\";\n\n\t\t\t@BeforeEach\n\t\t\tvoid pushAnElement() {\n\t\t\t\tstack.push(anElement);\n\t\t\t}\n\n\t\t\t@Test\n\t\t\t@DisplayName(\"it is no longer empty\")\n\t\t\tvoid isNotEmpty() {\n\t\t\t\tassertFalse(stack.isEmpty());\n\t\t\t}\n\n\t\t\t@Test\n\t\t\t@DisplayName(\"returns the element when popped and is empty\")\n\t\t\tvoid returnElementWhenPopped() {\n\t\t\t\tassertEquals(anElement, stack.pop());\n\t\t\t\tassertTrue(stack.isEmpty());\n\t\t\t}\n\n\t\t\t@Test\n\t\t\t@DisplayName(\"returns the element when peeked but remains not empty\")\n\t\t\tvoid returnElementWhenPeeked() {\n\t\t\t\tassertEquals(anElement, stack.peek());\n\t\t\t\tassertFalse(stack.isEmpty());\n\t\t\t}\n\t\t}\n\t}\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/TimeoutDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\nimport java.util.concurrent.TimeUnit;\n\nimport org.junit.jupiter.api.BeforeEach;\nimport org.junit.jupiter.api.Tag;\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.Timeout;\nimport org.junit.jupiter.api.Timeout.ThreadMode;\n\n// tag::user_guide[]\n@Tag(\"timeout\")\nclass TimeoutDemo {\n\n\t@BeforeEach\n\t@Timeout(5)\n\tvoid setUp() {\n\t\t// fails if execution time exceeds 5 seconds\n\t}\n\n\t@Test\n\t@Timeout(value = 500, unit = TimeUnit.MILLISECONDS)\n\tvoid failsIfExecutionTimeExceeds500Milliseconds() {\n\t\t// fails if execution time exceeds 500 milliseconds\n\t}\n\n\t@Test\n\t@Timeout(value = 500, unit = TimeUnit.MILLISECONDS, threadMode = ThreadMode.SEPARATE_THREAD)\n\tvoid failsIfExecutionTimeExceeds500MillisecondsInSeparateThread() {\n\t\t// fails if execution time exceeds 500 milliseconds, the test code is executed in a separate thread\n\t}\n\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/UsingTheLauncherDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\nimport static org.junit.platform.engine.TestExecutionResult.Status.FAILED;\nimport static org.junit.platform.engine.discovery.ClassNameFilter.includeClassNamePatterns;\nimport static org.junit.platform.engine.discovery.DiscoverySelectors.selectClass;\nimport static org.junit.platform.engine.discovery.DiscoverySelectors.selectPackage;\n\nimport java.io.PrintWriter;\nimport java.nio.file.Path;\n\nimport org.junit.jupiter.api.Tag;\nimport org.junit.jupiter.api.Test;\nimport org.junit.platform.engine.CancellationToken;\nimport org.junit.platform.engine.FilterResult;\nimport org.junit.platform.engine.TestDescriptor;\nimport org.junit.platform.engine.TestExecutionResult;\nimport org.junit.platform.launcher.Launcher;\nimport org.junit.platform.launcher.LauncherDiscoveryListener;\nimport org.junit.platform.launcher.LauncherDiscoveryRequest;\nimport org.junit.platform.launcher.LauncherExecutionRequest;\nimport org.junit.platform.launcher.LauncherSession;\nimport org.junit.platform.launcher.LauncherSessionListener;\nimport org.junit.platform.launcher.PostDiscoveryFilter;\nimport org.junit.platform.launcher.TestExecutionListener;\nimport org.junit.platform.launcher.TestIdentifier;\nimport org.junit.platform.launcher.TestPlan;\nimport org.junit.platform.launcher.core.LauncherConfig;\nimport org.junit.platform.launcher.core.LauncherDiscoveryRequestBuilder;\nimport org.junit.platform.launcher.core.LauncherExecutionRequestBuilder;\nimport org.junit.platform.launcher.core.LauncherFactory;\nimport org.junit.platform.launcher.listeners.SummaryGeneratingListener;\nimport org.junit.platform.launcher.listeners.TestExecutionSummary;\nimport org.junit.platform.reporting.legacy.xml.LegacyXmlReportGeneratingListener;\n\n/**\n * @since 5.0\n */\nclass UsingTheLauncherDemo {\n\n\t@Tag(\"exclude\")\n\t@Test\n\t@SuppressWarnings(\"unused\")\n\tvoid execution() {\n\t\t// @formatter:off\n\t\t// tag::execution[]\n\t\tLauncherDiscoveryRequest discoveryRequest = LauncherDiscoveryRequestBuilder.request()\n\t\t\t.selectors(\n\t\t\t\tselectPackage(\"com.example.mytests\"),\n\t\t\t\tselectClass(MyTestClass.class)\n\t\t\t)\n\t\t\t.filters(\n\t\t\t\tincludeClassNamePatterns(\".*Tests\")\n\t\t\t)\n\t\t\t// end::execution[]\n\t\t\t.configurationParameter(\"enableHttpServer\", \"false\")\n\t\t\t// tag::execution[]\n\t\t\t.build();\n\n\t\tSummaryGeneratingListener listener = new SummaryGeneratingListener();\n\n\t\ttry (LauncherSession session = LauncherFactory.openSession()) {\n\t\t\tLauncher launcher = session.getLauncher();\n\t\t\t// Register one ore more listeners of your choice.\n\t\t\tlauncher.registerTestExecutionListeners(listener);\n\t\t\t// Discover tests and build a test plan.\n\t\t\tTestPlan testPlan = launcher.discover(discoveryRequest);\n\t\t\t// Execute the test plan.\n\t\t\tlauncher.execute(testPlan);\n\t\t\t// Alternatively, execute the discovery request directly.\n\t\t\tlauncher.execute(discoveryRequest);\n\t\t}\n\n\t\tTestExecutionSummary summary = listener.getSummary();\n\t\t// Do something with the summary...\n\n\t\t// end::execution[]\n\t\t// @formatter:on\n\t}\n\n\t@Test\n\tvoid launcherConfig() {\n\t\tPath reportsDir = Path.of(\"target\", \"xml-reports\");\n\t\tPrintWriter out = new PrintWriter(System.out);\n\t\t// @formatter:off\n\t\t// tag::launcherConfig[]\n\t\tLauncherConfig launcherConfig = LauncherConfig.builder()\n\t\t\t.enableTestEngineAutoRegistration(false)\n\t\t\t.enableLauncherSessionListenerAutoRegistration(false)\n\t\t\t.enableLauncherDiscoveryListenerAutoRegistration(false)\n\t\t\t.enablePostDiscoveryFilterAutoRegistration(false)\n\t\t\t.enableTestExecutionListenerAutoRegistration(false)\n\t\t\t.addTestEngines(new CustomTestEngine())\n\t\t\t.addLauncherSessionListeners(new CustomLauncherSessionListener())\n\t\t\t.addLauncherDiscoveryListeners(new CustomLauncherDiscoveryListener())\n\t\t\t.addPostDiscoveryFilters(new CustomPostDiscoveryFilter())\n\t\t\t.addTestExecutionListeners(new LegacyXmlReportGeneratingListener(reportsDir, out))\n\t\t\t.addTestExecutionListeners(new CustomTestExecutionListener())\n\t\t\t.build();\n\n\t\tLauncherDiscoveryRequest discoveryRequest = LauncherDiscoveryRequestBuilder.request()\n\t\t\t.selectors(selectPackage(\"com.example.mytests\"))\n\t\t\t.build();\n\n\t\ttry (LauncherSession session = LauncherFactory.openSession(launcherConfig)) {\n\t\t\tsession.getLauncher().execute(discoveryRequest);\n\t\t}\n\t\t// end::launcherConfig[]\n\t\t// @formatter:on\n\t}\n\n\t@Test\n\t@SuppressWarnings(\"unused\")\n\tvoid cancellationDirect() {\n\t\t// tag::cancellation-direct[]\n\t\tCancellationToken cancellationToken = CancellationToken.create(); // <1>\n\n\t\tTestExecutionListener failFastListener = new TestExecutionListener() {\n\t\t\t@Override\n\t\t\tpublic void executionFinished(TestIdentifier identifier, TestExecutionResult result) {\n\t\t\t\tif (result.getStatus() == FAILED) {\n\t\t\t\t\tcancellationToken.cancel(); // <2>\n\t\t\t\t}\n\t\t\t}\n\t\t};\n\n\t\t// end::cancellation-direct[]\n\t\t// @formatter:off\n\t\t// tag::cancellation-direct[]\n\t\tLauncherExecutionRequest executionRequest = LauncherDiscoveryRequestBuilder.request()\n\t\t\t\t.selectors(selectClass(MyTestClass.class))\n\t\t\t\t.forExecution()\n\t\t\t\t// end::cancellation-direct[]\n\t\t\t\t// @formatter:on\n\t\t\t\t// tag::cancellation-direct[]\n\t\t\t\t.cancellationToken(cancellationToken) // <3>\n\t\t\t\t.listeners(failFastListener) // <4>\n\t\t\t\t.build();\n\n\t\ttry (LauncherSession session = LauncherFactory.openSession()) {\n\t\t\tsession.getLauncher().execute(executionRequest); // <5>\n\t\t}\n\t\t// end::cancellation-direct[]\n\t}\n\n\t@Test\n\t@SuppressWarnings(\"unused\")\n\tvoid cancellationFromDiscoveryRequest() {\n\t\tCancellationToken cancellationToken = CancellationToken.create();\n\n\t\tTestExecutionListener failFastListener = new TestExecutionListener() {\n\t\t\t@Override\n\t\t\tpublic void executionFinished(TestIdentifier identifier, TestExecutionResult result) {\n\t\t\t\tif (result.getStatus() == FAILED) {\n\t\t\t\t\tcancellationToken.cancel();\n\t\t\t\t}\n\t\t\t}\n\t\t};\n\n\t\t// @formatter:off\n\t\t// tag::cancellation-discovery-request[]\n\t\tLauncherDiscoveryRequest discoveryRequest = LauncherDiscoveryRequestBuilder.request()\n\t\t\t\t.selectors(selectClass(MyTestClass.class))\n\t\t\t\t.build(); // <1>\n\t\t// end::cancellation-discovery-request[]\n\t\t// @formatter:on\n\t\t// tag::cancellation-discovery-request[]\n\n\t\tLauncherExecutionRequest executionRequest = LauncherExecutionRequestBuilder.request(discoveryRequest) // <2>\n\t\t\t\t.cancellationToken(cancellationToken) // <3>\n\t\t\t\t.listeners(failFastListener) // <4>\n\t\t\t\t.build();\n\n\t\ttry (LauncherSession session = LauncherFactory.openSession()) {\n\t\t\tsession.getLauncher().execute(executionRequest); // <5>\n\t\t}\n\t\t// end::cancellation-discovery-request[]\n\t}\n\n\t@Test\n\t@SuppressWarnings(\"unused\")\n\tvoid cancellationFromTestPlan() {\n\t\tCancellationToken cancellationToken = CancellationToken.create();\n\n\t\tTestExecutionListener failFastListener = new TestExecutionListener() {\n\t\t\t@Override\n\t\t\tpublic void executionFinished(TestIdentifier identifier, TestExecutionResult result) {\n\t\t\t\tif (result.getStatus() == FAILED) {\n\t\t\t\t\tcancellationToken.cancel();\n\t\t\t\t}\n\t\t\t}\n\t\t};\n\n\t\t// @formatter:off\n\t\t// tag::cancellation-test-plan[]\n\t\tLauncherDiscoveryRequest discoveryRequest = LauncherDiscoveryRequestBuilder.request()\n\t\t\t\t.selectors(selectClass(MyTestClass.class))\n\t\t\t\t.build(); // <1>\n\t\t// end::cancellation-test-plan[]\n\t\t// @formatter:on\n\t\t// tag::cancellation-test-plan[]\n\n\t\ttry (LauncherSession session = LauncherFactory.openSession()) {\n\t\t\tvar launcher = session.getLauncher();\n\t\t\tTestPlan testPlan = launcher.discover(discoveryRequest); // <2>\n\t\t\tLauncherExecutionRequest executionRequest = LauncherExecutionRequestBuilder.request(testPlan) // <3>\n\t\t\t\t\t.cancellationToken(cancellationToken) // <4>\n\t\t\t\t\t.listeners(failFastListener) // <5>\n\t\t\t\t\t.build();\n\t\t\tlauncher.execute(executionRequest); // <6>\n\t\t}\n\t\t// end::cancellation-test-plan[]\n\t}\n\n}\n\nclass MyTestClass {\n}\n\nclass CustomTestExecutionListener implements TestExecutionListener {\n}\n\nclass CustomLauncherSessionListener implements LauncherSessionListener {\n}\n\nclass CustomLauncherDiscoveryListener implements LauncherDiscoveryListener {\n}\n\nclass CustomPostDiscoveryFilter implements PostDiscoveryFilter {\n\t@Override\n\tpublic FilterResult apply(TestDescriptor object) {\n\t\treturn FilterResult.included(\"includes everything\");\n\t}\n}\n"
},
{
"path": "documentation/src/test/java/example/UsingTheLauncherForDiscoveryDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example;\n\n// tag::imports[]\nimport static org.junit.platform.engine.discovery.ClassNameFilter.includeClassNamePatterns;\nimport static org.junit.platform.engine.discovery.DiscoverySelectors.selectClass;\nimport static org.junit.platform.engine.discovery.DiscoverySelectors.selectPackage;\nimport static org.junit.platform.launcher.core.LauncherDiscoveryRequestBuilder.discoveryRequest;\n\nimport org.junit.platform.launcher.LauncherDiscoveryRequest;\nimport org.junit.platform.launcher.LauncherSession;\nimport org.junit.platform.launcher.TestPlan;\nimport org.junit.platform.launcher.core.LauncherFactory;\n// end::imports[]\n\n/**\n * @since 6.0\n */\nclass UsingTheLauncherForDiscoveryDemo {\n\n\t@org.junit.jupiter.api.Test\n\t@SuppressWarnings(\"unused\")\n\tvoid discovery() {\n\t\t// @formatter:off\n\t\t// tag::discovery[]\n\t\tLauncherDiscoveryRequest discoveryRequest = discoveryRequest()\n\t\t\t.selectors(\n\t\t\t\tselectPackage(\"com.example.mytests\"),\n\t\t\t\tselectClass(MyTestClass.class)\n\t\t\t)\n\t\t\t.filters(\n\t\t\t\tincludeClassNamePatterns(\".*Tests\")\n\t\t\t)\n\t\t\t.build();\n\n\t\ttry (LauncherSession session = LauncherFactory.openSession()) {\n\t\t\tTestPlan testPlan = session.getLauncher().discover(discoveryRequest);\n\n\t\t\t// ... discover additional test plans or execute tests\n\t\t}\n\t\t// end::discovery[]\n\t\t// @formatter:on\n\t}\n\n\tstatic class MyTestClass {\n\t}\n\n}\n"
},
{
"path": "documentation/src/test/java/example/callbacks/AbstractDatabaseTests.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.callbacks;\n\n// tag::user_guide[]\n\nimport static example.callbacks.Logger.afterAllMethod;\nimport static example.callbacks.Logger.afterEachMethod;\nimport static example.callbacks.Logger.beforeAllMethod;\nimport static example.callbacks.Logger.beforeEachMethod;\n\nimport org.junit.jupiter.api.AfterAll;\nimport org.junit.jupiter.api.AfterEach;\nimport org.junit.jupiter.api.BeforeAll;\nimport org.junit.jupiter.api.BeforeEach;\n\n/**\n * Abstract base class for tests that use the database.\n */\nabstract class AbstractDatabaseTests {\n\n\t@BeforeAll\n\tstatic void createDatabase() {\n\t\tbeforeAllMethod(AbstractDatabaseTests.class.getSimpleName() + \".createDatabase()\");\n\t}\n\n\t@BeforeEach\n\tvoid connectToDatabase() {\n\t\tbeforeEachMethod(AbstractDatabaseTests.class.getSimpleName() + \".connectToDatabase()\");\n\t}\n\n\t@AfterEach\n\tvoid disconnectFromDatabase() {\n\t\tafterEachMethod(AbstractDatabaseTests.class.getSimpleName() + \".disconnectFromDatabase()\");\n\t}\n\n\t@AfterAll\n\tstatic void destroyDatabase() {\n\t\tafterAllMethod(AbstractDatabaseTests.class.getSimpleName() + \".destroyDatabase()\");\n\t}\n\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/callbacks/BrokenLifecycleMethodConfigDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.callbacks;\n\n// tag::user_guide[]\n\nimport static example.callbacks.Logger.afterEachMethod;\nimport static example.callbacks.Logger.beforeEachMethod;\nimport static example.callbacks.Logger.testMethod;\n\nimport org.junit.jupiter.api.AfterEach;\nimport org.junit.jupiter.api.BeforeEach;\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.extension.ExtendWith;\n\n/**\n * Example of \"broken\" lifecycle method configuration.\n *\n * Test data is inserted before the database connection has been opened.\n *\n *
Database connection is closed before deleting test data.\n */\n@ExtendWith({ Extension1.class, Extension2.class })\nclass BrokenLifecycleMethodConfigDemo {\n\n\t@BeforeEach\n\tvoid connectToDatabase() {\n\t\tbeforeEachMethod(getClass().getSimpleName() + \".connectToDatabase()\");\n\t}\n\n\t@BeforeEach\n\tvoid insertTestDataIntoDatabase() {\n\t\tbeforeEachMethod(getClass().getSimpleName() + \".insertTestDataIntoDatabase()\");\n\t}\n\n\t@Test\n\tvoid testDatabaseFunctionality() {\n\t\ttestMethod(getClass().getSimpleName() + \".testDatabaseFunctionality()\");\n\t}\n\n\t@AfterEach\n\tvoid deleteTestDataFromDatabase() {\n\t\tafterEachMethod(getClass().getSimpleName() + \".deleteTestDataFromDatabase()\");\n\t}\n\n\t@AfterEach\n\tvoid disconnectFromDatabase() {\n\t\tafterEachMethod(getClass().getSimpleName() + \".disconnectFromDatabase()\");\n\t}\n\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/callbacks/DatabaseTestsDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.callbacks;\n\n// tag::user_guide[]\n\nimport static example.callbacks.Logger.afterEachMethod;\nimport static example.callbacks.Logger.beforeAllMethod;\nimport static example.callbacks.Logger.beforeEachMethod;\nimport static example.callbacks.Logger.testMethod;\n\nimport org.junit.jupiter.api.AfterAll;\nimport org.junit.jupiter.api.AfterEach;\nimport org.junit.jupiter.api.BeforeAll;\nimport org.junit.jupiter.api.BeforeEach;\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.extension.ExtendWith;\n\n/**\n * Extension of {@link AbstractDatabaseTests} that inserts test data\n * into the database (after the database connection has been opened)\n * and deletes test data (before the database connection is closed).\n */\n@ExtendWith({ Extension1.class, Extension2.class })\nclass DatabaseTestsDemo extends AbstractDatabaseTests {\n\n\t@BeforeAll\n\tstatic void beforeAll() {\n\t\tbeforeAllMethod(DatabaseTestsDemo.class.getSimpleName() + \".beforeAll()\");\n\t}\n\n\t@BeforeEach\n\tvoid insertTestDataIntoDatabase() {\n\t\tbeforeEachMethod(getClass().getSimpleName() + \".insertTestDataIntoDatabase()\");\n\t}\n\n\t@Test\n\tvoid testDatabaseFunctionality() {\n\t\ttestMethod(getClass().getSimpleName() + \".testDatabaseFunctionality()\");\n\t}\n\n\t@AfterEach\n\tvoid deleteTestDataFromDatabase() {\n\t\tafterEachMethod(getClass().getSimpleName() + \".deleteTestDataFromDatabase()\");\n\t}\n\n\t@AfterAll\n\tstatic void afterAll() {\n\t\tbeforeAllMethod(DatabaseTestsDemo.class.getSimpleName() + \".afterAll()\");\n\t}\n\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/callbacks/Extension1.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.callbacks;\n\n// tag::user_guide[]\n\nimport static example.callbacks.Logger.afterEachCallback;\nimport static example.callbacks.Logger.beforeEachCallback;\n\nimport org.junit.jupiter.api.extension.AfterEachCallback;\nimport org.junit.jupiter.api.extension.BeforeEachCallback;\nimport org.junit.jupiter.api.extension.ExtensionContext;\n\npublic class Extension1 implements BeforeEachCallback, AfterEachCallback {\n\n\t@Override\n\tpublic void beforeEach(ExtensionContext context) {\n\t\tbeforeEachCallback(this);\n\t}\n\n\t@Override\n\tpublic void afterEach(ExtensionContext context) {\n\t\tafterEachCallback(this);\n\t}\n\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/callbacks/Extension2.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.callbacks;\n\n// tag::user_guide[]\n\nimport static example.callbacks.Logger.afterEachCallback;\nimport static example.callbacks.Logger.beforeEachCallback;\n\nimport org.junit.jupiter.api.extension.AfterEachCallback;\nimport org.junit.jupiter.api.extension.BeforeEachCallback;\nimport org.junit.jupiter.api.extension.ExtensionContext;\n\npublic class Extension2 implements BeforeEachCallback, AfterEachCallback {\n\n\t@Override\n\tpublic void beforeEach(ExtensionContext context) {\n\t\tbeforeEachCallback(this);\n\t}\n\n\t@Override\n\tpublic void afterEach(ExtensionContext context) {\n\t\tafterEachCallback(this);\n\t}\n\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/callbacks/Logger.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.callbacks;\n\nimport java.util.function.Supplier;\n\nimport org.junit.jupiter.api.extension.Extension;\n\nclass Logger {\n\n\tstatic final java.util.logging.Logger logger = java.util.logging.Logger.getLogger(Logger.class.getName());\n\n\tstatic void beforeAllMethod(String text) {\n\t\tlog(() -> \"@BeforeAll \" + text);\n\t}\n\n\tstatic void beforeEachCallback(Extension extension) {\n\t\tlog(() -> \" \" + extension.getClass().getSimpleName() + \".beforeEach()\");\n\t}\n\n\tstatic void beforeEachMethod(String text) {\n\t\tlog(() -> \" @BeforeEach \" + text);\n\t}\n\n\tstatic void testMethod(String text) {\n\t\tlog(() -> \" @Test \" + text);\n\t}\n\n\tstatic void afterEachMethod(String text) {\n\t\tlog(() -> \" @AfterEach \" + text);\n\t}\n\n\tstatic void afterEachCallback(Extension extension) {\n\t\tlog(() -> \" \" + extension.getClass().getSimpleName() + \".afterEach()\");\n\t}\n\n\tstatic void afterAllMethod(String text) {\n\t\tlog(() -> \"@AfterAll \" + text);\n\t}\n\n\tprivate static void log(Supplier supplier) {\n\t\t// System.err.println(supplier.get());\n\t\tlogger.info(supplier);\n\t}\n\n}\n"
},
{
"path": "documentation/src/test/java/example/callbacks/package-info.java",
"content": "\n@NullMarked\npackage example.callbacks;\n\nimport org.jspecify.annotations.NullMarked;\n"
},
{
"path": "documentation/src/test/java/example/defaultmethods/ComparableContract.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.defaultmethods;\n\nimport static org.junit.jupiter.api.Assertions.assertEquals;\nimport static org.junit.jupiter.api.Assertions.assertTrue;\n\nimport org.junit.jupiter.api.Test;\n\n// tag::user_guide[]\npublic interface ComparableContract> extends Testable {\n\n\tT createSmallerValue();\n\n\t@Test\n\tdefault void returnsZeroWhenComparedToItself() {\n\t\tT value = createValue();\n\t\tassertEquals(0, value.compareTo(value));\n\t}\n\n\t@Test\n\tdefault void returnsPositiveNumberWhenComparedToSmallerValue() {\n\t\tT value = createValue();\n\t\tT smallerValue = createSmallerValue();\n\t\tassertTrue(value.compareTo(smallerValue) > 0);\n\t}\n\n\t@Test\n\tdefault void returnsNegativeNumberWhenComparedToLargerValue() {\n\t\tT value = createValue();\n\t\tT smallerValue = createSmallerValue();\n\t\tassertTrue(smallerValue.compareTo(value) < 0);\n\t}\n\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/defaultmethods/EqualsContract.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.defaultmethods;\n\nimport static org.junit.jupiter.api.Assertions.assertEquals;\nimport static org.junit.jupiter.api.Assertions.assertNotEquals;\n\nimport org.junit.jupiter.api.Test;\n\n// tag::user_guide[]\npublic interface EqualsContract extends Testable {\n\n\tT createNotEqualValue();\n\n\t@Test\n\tdefault void valueEqualsItself() {\n\t\tT value = createValue();\n\t\tassertEquals(value, value);\n\t}\n\n\t@Test\n\tdefault void valueDoesNotEqualNull() {\n\t\tT value = createValue();\n\t\tassertNotEquals(null, value);\n\t}\n\n\t@Test\n\tdefault void valueDoesNotEqualDifferentValue() {\n\t\tT value = createValue();\n\t\tT differentValue = createNotEqualValue();\n\t\tassertNotEquals(value, differentValue);\n\t\tassertNotEquals(differentValue, value);\n\t}\n\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/defaultmethods/StringTests.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.defaultmethods;\n\n// tag::user_guide[]\nclass StringTests implements ComparableContract, EqualsContract {\n\n\t@Override\n\tpublic String createValue() {\n\t\treturn \"banana\";\n\t}\n\n\t@Override\n\tpublic String createSmallerValue() {\n\t\treturn \"apple\"; // 'a' < 'b' in \"banana\"\n\t}\n\n\t@Override\n\tpublic String createNotEqualValue() {\n\t\treturn \"cherry\";\n\t}\n\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/defaultmethods/Testable.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.defaultmethods;\n\n// tag::user_guide[]\npublic interface Testable {\n\n\tT createValue();\n\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/defaultmethods/package-info.java",
"content": "\n@NullMarked\npackage example.defaultmethods;\n\nimport org.jspecify.annotations.NullMarked;\n"
},
{
"path": "documentation/src/test/java/example/exception/AssertDoesNotThrowExceptionDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.exception;\n\nimport static org.junit.jupiter.api.Assertions.assertDoesNotThrow;\n\nimport org.junit.jupiter.api.Test;\n\nclass AssertDoesNotThrowExceptionDemo {\n\n\t// tag::user_guide[]\n\t@Test\n\tvoid testExceptionIsNotThrown() {\n\t\tassertDoesNotThrow(() -> {\n\t\t\tshouldNotThrowException();\n\t\t});\n\t}\n\n\tvoid shouldNotThrowException() {\n\t}\n\t// end::user_guide[]\n\n}\n"
},
{
"path": "documentation/src/test/java/example/exception/ExceptionAssertionDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.exception;\n\nimport static org.junit.jupiter.api.Assertions.assertEquals;\nimport static org.junit.jupiter.api.Assertions.assertThrows;\n\nimport org.junit.jupiter.api.Test;\n\nclass ExceptionAssertionDemo {\n\n\t// @formatter:off\n\t// tag::user_guide[]\n\t@Test\n\tvoid testExpectedExceptionIsThrown() {\n\t\t// The following assertion succeeds because the code under assertion\n\t\t// throws the expected IllegalArgumentException.\n\t\t// The assertion also returns the thrown exception which can be used for\n\t\t// further assertions like asserting the exception message.\n\t\tIllegalArgumentException exception =\n\t\t\tassertThrows(IllegalArgumentException.class, () -> {\n\t\t\t\tthrow new IllegalArgumentException(\"expected message\");\n\t\t\t});\n\t\tassertEquals(\"expected message\", exception.getMessage());\n\n\t\t// The following assertion also succeeds because the code under assertion\n\t\t// throws IllegalArgumentException which is a subclass of RuntimeException.\n\t\tassertThrows(RuntimeException.class, () -> {\n\t\t\tthrow new IllegalArgumentException(\"expected message\");\n\t\t});\n\t}\n\t// end::user_guide[]\n\t// @formatter:on\n\n}\n"
},
{
"path": "documentation/src/test/java/example/exception/ExceptionAssertionExactDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.exception;\n\nimport static org.junit.jupiter.api.Assertions.assertEquals;\nimport static org.junit.jupiter.api.Assertions.assertThrowsExactly;\n\nimport extensions.ExpectToFail;\n\nimport org.junit.jupiter.api.Test;\n\npublic class ExceptionAssertionExactDemo {\n\n\t@ExpectToFail\n\t// @formatter:off\n\t// tag::user_guide[]\n\t@Test\n\tvoid testExpectedExceptionIsThrown() {\n\t\t// The following assertion succeeds because the code under assertion throws\n\t\t// IllegalArgumentException which is exactly equal to the expected type.\n\t\t// The assertion also returns the thrown exception which can be used for\n\t\t// further assertions like asserting the exception message.\n\t\tIllegalArgumentException exception =\n\t\t\tassertThrowsExactly(IllegalArgumentException.class, () -> {\n\t\t\t\tthrow new IllegalArgumentException(\"expected message\");\n\t\t\t});\n\t\tassertEquals(\"expected message\", exception.getMessage());\n\n\t\t// The following assertion fails because the assertion expects exactly\n\t\t// RuntimeException to be thrown, not subclasses of RuntimeException.\n\t\tassertThrowsExactly(RuntimeException.class, () -> {\n\t\t\tthrow new IllegalArgumentException(\"expected message\");\n\t\t});\n\t}\n\t// end::user_guide[]\n\t// @formatter:on\n\n}\n"
},
{
"path": "documentation/src/test/java/example/exception/FailedAssertionDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.exception;\n\nimport static org.junit.jupiter.api.Assertions.assertEquals;\n\nimport example.util.Calculator;\n\nimport extensions.ExpectToFail;\n\nimport org.junit.jupiter.api.Test;\n\nclass FailedAssertionDemo {\n\n\t// tag::user_guide[]\n\tprivate final Calculator calculator = new Calculator();\n\n\t// end::user_guide[]\n\n\t@ExpectToFail\n\t// tag::user_guide[]\n\t@Test\n\tvoid failsDueToUncaughtAssertionError() {\n\t\t// The following incorrect assertion will cause a test failure.\n\t\t// The expected value should be 2 instead of 99.\n\t\tassertEquals(99, calculator.add(1, 1));\n\t}\n\t// end::user_guide[]\n\n}\n"
},
{
"path": "documentation/src/test/java/example/exception/IgnoreIOExceptionExtension.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.exception;\n\nimport java.io.IOException;\n\nimport org.junit.jupiter.api.extension.ExtensionContext;\nimport org.junit.jupiter.api.extension.TestExecutionExceptionHandler;\n\n// @formatter:off\n// tag::user_guide[]\npublic class IgnoreIOExceptionExtension implements TestExecutionExceptionHandler {\n\n\t@Override\n\tpublic void handleTestExecutionException(ExtensionContext context, Throwable throwable)\n\t\t\tthrows Throwable {\n\n\t\tif (throwable instanceof IOException) {\n\t\t\treturn;\n\t\t}\n\t\tthrow throwable;\n\t}\n}\n// end::user_guide[]\n// @formatter:on\n"
},
{
"path": "documentation/src/test/java/example/exception/IgnoreIOExceptionTests.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.exception;\n\nimport java.io.IOException;\n\nimport extensions.ExpectToFail;\n\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.extension.ExtendWith;\n\n@ExtendWith(IgnoreIOExceptionExtension.class)\nclass IgnoreIOExceptionTests {\n\n\t@Test\n\tvoid shouldSucceed() throws IOException {\n\t\tthrow new IOException(\"any\");\n\t}\n\n\t@Test\n\t@ExpectToFail\n\tvoid shouldFail() {\n\t\tthrow new RuntimeException(\"any\");\n\t}\n}\n"
},
{
"path": "documentation/src/test/java/example/exception/MultipleHandlersTestCase.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.exception;\n\nimport example.exception.MultipleHandlersTestCase.ThirdExecutedHandler;\n\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.extension.ExtendWith;\nimport org.junit.jupiter.api.extension.ExtensionContext;\nimport org.junit.jupiter.api.extension.LifecycleMethodExecutionExceptionHandler;\nimport org.junit.jupiter.api.extension.TestExecutionExceptionHandler;\n\n// @formatter:off\n// tag::user_guide[]\n// Register handlers for @Test, @BeforeEach, @AfterEach as well as @BeforeAll and @AfterAll\n@ExtendWith(ThirdExecutedHandler.class)\nclass MultipleHandlersTestCase {\n\n\t// Register handlers for @Test, @BeforeEach, @AfterEach only\n\t@ExtendWith(SecondExecutedHandler.class)\n\t@ExtendWith(FirstExecutedHandler.class)\n\t@Test\n\tvoid testMethod() {\n\t}\n\n\t// end::user_guide[]\n\n\tstatic class FirstExecutedHandler implements TestExecutionExceptionHandler {\n\t\t@Override\n\t\tpublic void handleTestExecutionException(ExtensionContext context, Throwable ex)\n\t\t\t\tthrows Throwable {\n\t\t\tthrow ex;\n\t\t}\n\t}\n\n\tstatic class SecondExecutedHandler implements LifecycleMethodExecutionExceptionHandler {\n\t\t@Override\n\t\tpublic void handleBeforeEachMethodExecutionException(ExtensionContext context, Throwable ex)\n\t\t\t\tthrows Throwable {\n\t\t\tthrow ex;\n\t\t}\n\t}\n\n\tstatic class ThirdExecutedHandler implements LifecycleMethodExecutionExceptionHandler {\n\t\t@Override\n\t\tpublic void handleBeforeAllMethodExecutionException(ExtensionContext context, Throwable ex)\n\t\t\t\tthrows Throwable {\n\t\t\tthrow ex;\n\t\t}\n\t}\n\t// tag::user_guide[]\n}\n// end::user_guide[]\n// @formatter:on\n"
},
{
"path": "documentation/src/test/java/example/exception/RecordStateOnErrorExtension.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.exception;\n\nimport org.junit.jupiter.api.extension.ExtensionContext;\nimport org.junit.jupiter.api.extension.LifecycleMethodExecutionExceptionHandler;\n\n// @formatter:off\n// tag::user_guide[]\nclass RecordStateOnErrorExtension implements LifecycleMethodExecutionExceptionHandler {\n\n\t@Override\n\tpublic void handleBeforeAllMethodExecutionException(ExtensionContext context, Throwable ex)\n\t\t\tthrows Throwable {\n\t\tmemoryDumpForFurtherInvestigation(\"Failure recorded during class setup\");\n\t\tthrow ex;\n\t}\n\n\t@Override\n\tpublic void handleBeforeEachMethodExecutionException(ExtensionContext context, Throwable ex)\n\t\t\tthrows Throwable {\n\t\tmemoryDumpForFurtherInvestigation(\"Failure recorded during test setup\");\n\t\tthrow ex;\n\t}\n\n\t@Override\n\tpublic void handleAfterEachMethodExecutionException(ExtensionContext context, Throwable ex)\n\t\t\tthrows Throwable {\n\t\tmemoryDumpForFurtherInvestigation(\"Failure recorded during test cleanup\");\n\t\tthrow ex;\n\t}\n\n\t@Override\n\tpublic void handleAfterAllMethodExecutionException(ExtensionContext context, Throwable ex)\n\t\t\tthrows Throwable {\n\t\tmemoryDumpForFurtherInvestigation(\"Failure recorded during class cleanup\");\n\t\tthrow ex;\n\t}\n\t// end::user_guide[]\n\n\tprivate void memoryDumpForFurtherInvestigation(String error) {\n\t}\n\t// tag::user_guide[]\n}\n// end::user_guide[]\n// @formatter:on\n"
},
{
"path": "documentation/src/test/java/example/exception/UncaughtExceptionHandlingDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.exception;\n\nimport example.util.Calculator;\n\nimport extensions.ExpectToFail;\n\nimport org.junit.jupiter.api.Test;\n\nclass UncaughtExceptionHandlingDemo {\n\n\t// tag::user_guide[]\n\tprivate final Calculator calculator = new Calculator();\n\n\t// end::user_guide[]\n\n\t@ExpectToFail\n\t// tag::user_guide[]\n\t@Test\n\tvoid failsDueToUncaughtException() {\n\t\t// The following throws an ArithmeticException due to division by\n\t\t// zero, which causes a test failure.\n\t\tcalculator.divide(1, 0);\n\t}\n\t// end::user_guide[]\n\n}\n"
},
{
"path": "documentation/src/test/java/example/exception/package-info.java",
"content": "\n@NullMarked\npackage example.exception;\n\nimport org.jspecify.annotations.NullMarked;\n"
},
{
"path": "documentation/src/test/java/example/extensions/HttpServerExtension.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.extensions;\n\nimport java.io.IOException;\nimport java.io.UncheckedIOException;\n\nimport com.sun.net.httpserver.HttpServer;\n\nimport org.junit.jupiter.api.extension.ExtensionContext;\nimport org.junit.jupiter.api.extension.ExtensionContext.Namespace;\nimport org.junit.jupiter.api.extension.ParameterContext;\nimport org.junit.jupiter.api.extension.ParameterResolver;\n\n// tag::user_guide[]\npublic class HttpServerExtension implements ParameterResolver {\n\n\t@Override\n\tpublic boolean supportsParameter(ParameterContext parameterContext, ExtensionContext extensionContext) {\n\t\treturn HttpServer.class.equals(parameterContext.getParameter().getType());\n\t}\n\n\t@Override\n\tpublic Object resolveParameter(ParameterContext parameterContext, ExtensionContext extensionContext) {\n\n\t\tExtensionContext rootContext = extensionContext.getRoot();\n\t\tExtensionContext.Store store = rootContext.getStore(Namespace.GLOBAL);\n\t\tClass key = HttpServerResource.class;\n\t\tHttpServerResource resource = store.computeIfAbsent(key, __ -> {\n\t\t\ttry {\n\t\t\t\tHttpServerResource serverResource = new HttpServerResource(0);\n\t\t\t\tserverResource.start();\n\t\t\t\treturn serverResource;\n\t\t\t}\n\t\t\tcatch (IOException e) {\n\t\t\t\tthrow new UncheckedIOException(\"Failed to create HttpServerResource\", e);\n\t\t\t}\n\t\t}, HttpServerResource.class);\n\t\treturn resource.getHttpServer();\n\t}\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/extensions/HttpServerResource.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.extensions;\n\nimport static java.nio.charset.StandardCharsets.UTF_8;\n\nimport java.io.IOException;\nimport java.io.OutputStream;\nimport java.net.InetAddress;\nimport java.net.InetSocketAddress;\n\nimport com.sun.net.httpserver.HttpServer;\n\n/**\n * Demonstrates an implementation of {@link AutoCloseable} using an {@link HttpServer}.\n */\n// tag::user_guide[]\nclass HttpServerResource implements AutoCloseable {\n\n\tprivate final HttpServer httpServer;\n\n\t// end::user_guide[]\n\n\t/**\n\t * Initializes the Http server resource, using the given port.\n\t *\n\t * @param port (int) The port number for the server, must be in the range 0-65535.\n\t * @throws IOException if an IOException occurs during initialization.\n\t */\n\t// tag::user_guide[]\n\tHttpServerResource(int port) throws IOException {\n\t\tInetAddress loopbackAddress = InetAddress.getLoopbackAddress();\n\t\tthis.httpServer = HttpServer.create(new InetSocketAddress(loopbackAddress, port), 0);\n\t}\n\n\tHttpServer getHttpServer() {\n\t\treturn httpServer;\n\t}\n\n\t// end::user_guide[]\n\n\t/**\n\t * Starts the Http server with an example handler.\n\t */\n\t// tag::user_guide[]\n\tvoid start() {\n\t\t// Example handler\n\t\thttpServer.createContext(\"/example\", exchange -> {\n\t\t\tString body = \"This is a test\";\n\t\t\texchange.sendResponseHeaders(200, body.length());\n\t\t\ttry (OutputStream os = exchange.getResponseBody()) {\n\t\t\t\tos.write(body.getBytes(UTF_8));\n\t\t\t}\n\t\t});\n\t\thttpServer.setExecutor(null);\n\t\thttpServer.start();\n\t}\n\n\t@Override\n\tpublic void close() {\n\t\thttpServer.stop(0);\n\t}\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/extensions/ParameterResolverConflictDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.extensions;\n\nimport static org.junit.jupiter.api.Assertions.assertEquals;\n\nimport extensions.ExpectToFail;\n\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.extension.ExtendWith;\nimport org.junit.jupiter.api.extension.ExtensionContext;\nimport org.junit.jupiter.api.extension.ParameterContext;\nimport org.junit.jupiter.api.extension.ParameterResolver;\n\n// tag::user_guide[]\npublic class ParameterResolverConflictDemo {\n\n\t// end::user_guide[]\n\t@ExpectToFail\n\t// tag::user_guide[]\n\t@Test\n\t@ExtendWith({ FirstIntegerResolver.class, SecondIntegerResolver.class })\n\tvoid testInt(int i) {\n\t\t// Test will not run due to ParameterResolutionException\n\t\tassertEquals(1, i);\n\t}\n\n\tstatic class FirstIntegerResolver implements ParameterResolver {\n\n\t\t@Override\n\t\tpublic boolean supportsParameter(ParameterContext parameterContext, ExtensionContext extensionContext) {\n\t\t\treturn parameterContext.getParameter().getType() == int.class;\n\t\t}\n\n\t\t@Override\n\t\tpublic Object resolveParameter(ParameterContext parameterContext, ExtensionContext extensionContext) {\n\t\t\treturn 1;\n\t\t}\n\t}\n\n\tstatic class SecondIntegerResolver implements ParameterResolver {\n\n\t\t@Override\n\t\tpublic boolean supportsParameter(ParameterContext parameterContext, ExtensionContext extensionContext) {\n\t\t\treturn parameterContext.getParameter().getType() == int.class;\n\t\t}\n\n\t\t@Override\n\t\tpublic Object resolveParameter(ParameterContext parameterContext, ExtensionContext extensionContext) {\n\t\t\treturn 2;\n\t\t}\n\t}\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/extensions/ParameterResolverCustomAnnotationDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.extensions;\n\nimport static org.junit.jupiter.api.Assertions.assertEquals;\n\nimport java.lang.annotation.ElementType;\nimport java.lang.annotation.Retention;\nimport java.lang.annotation.RetentionPolicy;\nimport java.lang.annotation.Target;\n\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.extension.ExtendWith;\nimport org.junit.jupiter.api.extension.ExtensionContext;\nimport org.junit.jupiter.api.extension.ParameterContext;\nimport org.junit.jupiter.api.extension.ParameterResolver;\n\n// tag::user_guide[]\npublic class ParameterResolverCustomAnnotationDemo {\n\n\t@Test\n\tvoid testInt(@FirstInteger Integer first, @SecondInteger Integer second) {\n\t\tassertEquals(1, first);\n\t\tassertEquals(2, second);\n\t}\n\n\t@Target(ElementType.PARAMETER)\n\t@Retention(RetentionPolicy.RUNTIME)\n\t@ExtendWith(FirstInteger.Extension.class)\n\tpublic @interface FirstInteger {\n\n\t\tclass Extension implements ParameterResolver {\n\n\t\t\t@Override\n\t\t\tpublic boolean supportsParameter(ParameterContext parameterContext, ExtensionContext extensionContext) {\n\t\t\t\treturn parameterContext.getParameter().getType().equals(Integer.class)\n\t\t\t\t\t\t&& !parameterContext.isAnnotated(SecondInteger.class);\n\t\t\t}\n\n\t\t\t@Override\n\t\t\tpublic Object resolveParameter(ParameterContext parameterContext, ExtensionContext extensionContext) {\n\t\t\t\treturn 1;\n\t\t\t}\n\t\t}\n\t}\n\n\t@Target(ElementType.PARAMETER)\n\t@Retention(RetentionPolicy.RUNTIME)\n\t@ExtendWith(SecondInteger.Extension.class)\n\tpublic @interface SecondInteger {\n\n\t\tclass Extension implements ParameterResolver {\n\n\t\t\t@Override\n\t\t\tpublic boolean supportsParameter(ParameterContext parameterContext, ExtensionContext extensionContext) {\n\t\t\t\treturn parameterContext.isAnnotated(SecondInteger.class);\n\t\t\t}\n\n\t\t\t@Override\n\t\t\tpublic Object resolveParameter(ParameterContext parameterContext, ExtensionContext extensionContext) {\n\t\t\t\treturn 2;\n\t\t\t}\n\t\t}\n\t}\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/extensions/ParameterResolverCustomTypeDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.extensions;\n\nimport static org.junit.jupiter.api.Assertions.assertEquals;\n\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.extension.ExtendWith;\nimport org.junit.jupiter.api.extension.ExtensionContext;\nimport org.junit.jupiter.api.extension.ParameterContext;\nimport org.junit.jupiter.api.extension.ParameterResolver;\n\n// tag::user_guide[]\npublic class ParameterResolverCustomTypeDemo {\n\n\t@Test\n\t@ExtendWith({ FirstIntegerResolver.class, SecondIntegerResolver.class })\n\tvoid testInt(Integer i, WrappedInteger wrappedInteger) {\n\t\tassertEquals(1, i);\n\t\tassertEquals(2, wrappedInteger.value);\n\t}\n\n\tstatic class FirstIntegerResolver implements ParameterResolver {\n\n\t\t@Override\n\t\tpublic boolean supportsParameter(ParameterContext parameterContext, ExtensionContext extensionContext) {\n\t\t\treturn parameterContext.getParameter().getType().equals(Integer.class);\n\t\t}\n\n\t\t@Override\n\t\tpublic Object resolveParameter(ParameterContext parameterContext, ExtensionContext extensionContext) {\n\t\t\treturn 1;\n\t\t}\n\t}\n\n\tstatic class SecondIntegerResolver implements ParameterResolver {\n\n\t\t@Override\n\t\tpublic boolean supportsParameter(ParameterContext parameterContext, ExtensionContext extensionContext) {\n\t\t\treturn parameterContext.getParameter().getType().equals(WrappedInteger.class);\n\t\t}\n\n\t\t@Override\n\t\tpublic Object resolveParameter(ParameterContext parameterContext, ExtensionContext extensionContext) {\n\t\t\treturn new WrappedInteger(2);\n\t\t}\n\t}\n\n\tstatic class WrappedInteger {\n\n\t\tprivate final int value;\n\n\t\tWrappedInteger(int value) {\n\t\t\tthis.value = value;\n\t\t}\n\n\t}\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/extensions/ParameterResolverNoConflictDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.extensions;\n\nimport static org.junit.jupiter.api.Assertions.assertEquals;\n\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.extension.ExtendWith;\nimport org.junit.jupiter.api.extension.ExtensionContext;\nimport org.junit.jupiter.api.extension.ParameterContext;\nimport org.junit.jupiter.api.extension.ParameterResolver;\n\n// tag::user_guide[]\npublic class ParameterResolverNoConflictDemo {\n\n\t@Test\n\t@ExtendWith(FirstIntegerResolver.class)\n\tvoid firstResolution(int i) {\n\t\tassertEquals(1, i);\n\t}\n\n\t@Test\n\t@ExtendWith(SecondIntegerResolver.class)\n\tvoid secondResolution(int i) {\n\t\tassertEquals(2, i);\n\t}\n\n\tstatic class FirstIntegerResolver implements ParameterResolver {\n\n\t\t@Override\n\t\tpublic boolean supportsParameter(ParameterContext parameterContext, ExtensionContext extensionContext) {\n\t\t\treturn parameterContext.getParameter().getType() == int.class;\n\t\t}\n\n\t\t@Override\n\t\tpublic Object resolveParameter(ParameterContext parameterContext, ExtensionContext extensionContext) {\n\t\t\treturn 1;\n\t\t}\n\t}\n\n\tstatic class SecondIntegerResolver implements ParameterResolver {\n\n\t\t@Override\n\t\tpublic boolean supportsParameter(ParameterContext parameterContext, ExtensionContext extensionContext) {\n\t\t\treturn parameterContext.getParameter().getType() == int.class;\n\t\t}\n\n\t\t@Override\n\t\tpublic Object resolveParameter(ParameterContext parameterContext, ExtensionContext extensionContext) {\n\t\t\treturn 2;\n\t\t}\n\t}\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/extensions/Random.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.extensions;\n\nimport java.lang.annotation.ElementType;\nimport java.lang.annotation.Retention;\nimport java.lang.annotation.RetentionPolicy;\nimport java.lang.annotation.Target;\n\nimport org.junit.jupiter.api.extension.ExtendWith;\n\n//tag::user_guide[]\n@Target({ ElementType.FIELD, ElementType.PARAMETER })\n@Retention(RetentionPolicy.RUNTIME)\n@ExtendWith(RandomNumberExtension.class)\npublic @interface Random {\n}\n//end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/extensions/RandomNumberDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.extensions;\n\nimport org.jspecify.annotations.Nullable;\nimport org.junit.jupiter.api.BeforeEach;\nimport org.junit.jupiter.api.Test;\n\n// tag::user_guide[]\nclass RandomNumberDemo {\n\n\t// Use static randomNumber0 field anywhere in the test class,\n\t// including @BeforeAll or @AfterEach lifecycle methods.\n\t@Random\n\t// end::user_guide[]\n\t@Nullable\n\t// tag::user_guide[]\n\tprivate static Integer randomNumber0;\n\n\t// Use randomNumber1 field in test methods and @BeforeEach\n\t// or @AfterEach lifecycle methods.\n\t@Random\n\tprivate int randomNumber1;\n\n\tRandomNumberDemo(@Random int randomNumber2) {\n\t\t// Use randomNumber2 in constructor.\n\t}\n\n\t@BeforeEach\n\tvoid beforeEach(@Random int randomNumber3) {\n\t\t// Use randomNumber3 in @BeforeEach method.\n\t}\n\n\t@Test\n\tvoid test(@Random int randomNumber4) {\n\t\t// Use randomNumber4 in test method.\n\t}\n\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/extensions/RandomNumberExtension.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.extensions;\n\n// tag::user_guide[]\n\nimport static org.junit.platform.commons.support.AnnotationSupport.findAnnotatedFields;\n\nimport java.lang.reflect.Field;\nimport java.util.function.Predicate;\n\nimport org.jspecify.annotations.Nullable;\nimport org.junit.jupiter.api.extension.BeforeAllCallback;\nimport org.junit.jupiter.api.extension.ExtensionContext;\nimport org.junit.jupiter.api.extension.ParameterContext;\nimport org.junit.jupiter.api.extension.ParameterResolver;\nimport org.junit.jupiter.api.extension.TestInstancePostProcessor;\nimport org.junit.platform.commons.support.ModifierSupport;\n\n// end::user_guide[]\n// @formatter:off\n// tag::user_guide[]\nclass RandomNumberExtension\n\t\timplements BeforeAllCallback, TestInstancePostProcessor, ParameterResolver {\n\n\tprivate final java.util.Random random = new java.util.Random(System.nanoTime());\n\n\t/**\n\t * Inject a random integer into static fields that are annotated with\n\t * {@code @Random} and can be assigned an integer value.\n\t */\n\t@Override\n\tpublic void beforeAll(ExtensionContext context) {\n\t\tClass testClass = context.getRequiredTestClass();\n\t\tinjectFields(testClass, null, ModifierSupport::isStatic);\n\t}\n\n\t/**\n\t * Inject a random integer into non-static fields that are annotated with\n\t * {@code @Random} and can be assigned an integer value.\n\t */\n\t@Override\n\tpublic void postProcessTestInstance(Object testInstance, ExtensionContext context) {\n\t\tClass testClass = context.getRequiredTestClass();\n\t\tinjectFields(testClass, testInstance, ModifierSupport::isNotStatic);\n\t}\n\n\t/**\n\t * Determine if the parameter is annotated with {@code @Random} and can be\n\t * assigned an integer value.\n\t */\n\t@Override\n\tpublic boolean supportsParameter(ParameterContext pc, ExtensionContext ec) {\n\t\treturn pc.isAnnotated(Random.class) && isInteger(pc.getParameter().getType());\n\t}\n\n\t/**\n\t * Resolve a random integer.\n\t */\n\t@Override\n\tpublic Integer resolveParameter(ParameterContext pc, ExtensionContext ec) {\n\t\treturn this.random.nextInt();\n\t}\n\n\tprivate void injectFields(Class testClass, @Nullable Object testInstance,\n\t\t\tPredicate predicate) {\n\n\t\tpredicate = predicate.and(field -> isInteger(field.getType()));\n\t\tfindAnnotatedFields(testClass, Random.class, predicate)\n\t\t\t.forEach(field -> {\n\t\t\t\ttry {\n\t\t\t\t\tfield.setAccessible(true);\n\t\t\t\t\tfield.set(testInstance, this.random.nextInt());\n\t\t\t\t}\n\t\t\t\tcatch (Exception ex) {\n\t\t\t\t\tthrow new RuntimeException(ex);\n\t\t\t\t}\n\t\t\t});\n\t}\n\n\tprivate static boolean isInteger(Class type) {\n\t\treturn type == Integer.class || type == int.class;\n\t}\n\n}\n// end::user_guide[]\n// @formatter:on\n"
},
{
"path": "documentation/src/test/java/example/extensions/package-info.java",
"content": "\n@NullMarked\npackage example.extensions;\n\nimport org.jspecify.annotations.NullMarked;\n"
},
{
"path": "documentation/src/test/java/example/interceptor/SwingEdtInterceptor.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.interceptor;\n\nimport java.lang.reflect.Method;\nimport java.util.concurrent.atomic.AtomicReference;\n\nimport javax.swing.SwingUtilities;\n\nimport org.junit.jupiter.api.extension.ExtensionContext;\nimport org.junit.jupiter.api.extension.InvocationInterceptor;\nimport org.junit.jupiter.api.extension.ReflectiveInvocationContext;\n\n// @formatter:off\n// tag::user_guide[]\npublic class SwingEdtInterceptor implements InvocationInterceptor {\n\n\t//end::user_guide[]\n\t@SuppressWarnings(\"NullAway\")\n\t//tag::user_guide[]\n\t@Override\n\tpublic void interceptTestMethod(Invocation invocation,\n\t\t\tReflectiveInvocationContext invocationContext,\n\t\t\tExtensionContext extensionContext) throws Throwable {\n\n\t\tAtomicReference throwable = new AtomicReference<>();\n\n\t\tSwingUtilities.invokeAndWait(() -> {\n\t\t\ttry {\n\t\t\t\tinvocation.proceed();\n\t\t\t}\n\t\t\tcatch (Throwable t) {\n\t\t\t\tthrowable.set(t);\n\t\t\t}\n\t\t});\n\t\tThrowable t = throwable.get();\n\t\tif (t != null) {\n\t\t\tthrow t;\n\t\t}\n\t}\n}\n// end::user_guide[]\n// @formatter:on\n"
},
{
"path": "documentation/src/test/java/example/interceptor/package-info.java",
"content": "\n@NullMarked\npackage example.interceptor;\n\nimport org.jspecify.annotations.NullMarked;\n"
},
{
"path": "documentation/src/test/java/example/package-info.java",
"content": "\n@NullMarked\npackage example;\n\nimport org.jspecify.annotations.NullMarked;\n"
},
{
"path": "documentation/src/test/java/example/registration/DocumentationDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.registration;\n\nimport java.nio.file.Path;\n\nimport org.jspecify.annotations.NullMarked;\nimport org.jspecify.annotations.Nullable;\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.extension.AfterEachCallback;\nimport org.junit.jupiter.api.extension.ExtensionContext;\nimport org.junit.jupiter.api.extension.RegisterExtension;\n\n//tag::user_guide[]\nclass DocumentationDemo {\n\n\t//end::user_guide[]\n\t@Nullable\n\t//tag::user_guide[]\n\tstatic Path lookUpDocsDir() {\n\t\t// return path to docs dir\n\t\t// end::user_guide[]\n\t\treturn null;\n\t\t// tag::user_guide[]\n\t}\n\n\t@RegisterExtension\n\tDocumentationExtension docs = DocumentationExtension.forPath(lookUpDocsDir());\n\n\t@Test\n\tvoid generateDocumentation() {\n\t\t// use this.docs ...\n\t}\n}\n//end::user_guide[]\n\n@NullMarked\nclass DocumentationExtension implements AfterEachCallback {\n\n\t@SuppressWarnings(\"unused\")\n\tprivate final @Nullable Path path;\n\n\tprivate DocumentationExtension(@Nullable Path path) {\n\t\tthis.path = path;\n\t}\n\n\tstatic DocumentationExtension forPath(@Nullable Path path) {\n\t\treturn new DocumentationExtension(path);\n\t}\n\n\t@Override\n\tpublic void afterEach(ExtensionContext context) {\n\t\t/* no-op for demo */\n\t}\n\n}\n"
},
{
"path": "documentation/src/test/java/example/registration/WebServerDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.registration;\n\nimport static org.junit.jupiter.api.Assertions.assertEquals;\n\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.extension.RegisterExtension;\n\n// tag::user_guide[]\nclass WebServerDemo {\n\n\t// end::user_guide[]\n\t// @formatter:off\n\t// tag::user_guide[]\n\t@RegisterExtension\n\tstatic WebServerExtension server = WebServerExtension.builder()\n\t\t.enableSecurity(false)\n\t\t.build();\n\t// end::user_guide[]\n\t// @formatter:on\n\t// tag::user_guide[]\n\n\t@Test\n\tvoid getProductList() {\n\t\t// end::user_guide[]\n\t\t@SuppressWarnings(\"resource\")\n\t\t// tag::user_guide[]\n\t\tWebClient webClient = new WebClient();\n\t\tString serverUrl = server.getServerUrl();\n\t\t// Use WebClient to connect to web server using serverUrl and verify response\n\t\tassertEquals(200, webClient.get(serverUrl + \"/products\").getResponseStatus());\n\t}\n\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/session/CloseableHttpServer.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.session;\n\n//tag::user_guide[]\nimport java.util.concurrent.ExecutorService;\n\nimport com.sun.net.httpserver.HttpServer;\n\npublic class CloseableHttpServer implements AutoCloseable {\n\n\tprivate final HttpServer server;\n\tprivate final ExecutorService executorService;\n\n\tCloseableHttpServer(HttpServer server, ExecutorService executorService) {\n\t\tthis.server = server;\n\t\tthis.executorService = executorService;\n\t}\n\n\tpublic HttpServer getServer() {\n\t\treturn server;\n\t}\n\n\t@Override\n\tpublic void close() { // <1>\n\t\tserver.stop(0); // <2>\n\t\texecutorService.shutdownNow();\n\t}\n}\n//end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/session/GlobalSetupTeardownListener.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.session;\n\n//tag::user_guide[]\nimport static java.net.InetAddress.getLoopbackAddress;\n\nimport java.io.IOException;\nimport java.io.UncheckedIOException;\nimport java.net.InetSocketAddress;\nimport java.util.concurrent.ExecutorService;\nimport java.util.concurrent.Executors;\n\nimport com.sun.net.httpserver.HttpServer;\n\nimport org.junit.platform.engine.support.store.Namespace;\nimport org.junit.platform.engine.support.store.NamespacedHierarchicalStore;\nimport org.junit.platform.launcher.LauncherSession;\nimport org.junit.platform.launcher.LauncherSessionListener;\nimport org.junit.platform.launcher.TestExecutionListener;\nimport org.junit.platform.launcher.TestPlan;\n\npublic class GlobalSetupTeardownListener implements LauncherSessionListener {\n\n\t@Override\n\tpublic void launcherSessionOpened(LauncherSession session) {\n\t\t// Avoid setup for test discovery by delaying it until tests are about to be executed\n\t\tsession.getLauncher().registerTestExecutionListeners(new TestExecutionListener() {\n\t\t\t@Override\n\t\t\tpublic void testPlanExecutionStarted(TestPlan testPlan) {\n\t\t\t\t//end::user_guide[]\n\t\t\t\tif (!testPlan.getConfigurationParameters().getBoolean(\"enableHttpServer\").orElse(true)) {\n\t\t\t\t\t// avoid starting multiple HTTP servers unnecessarily from UsingTheLauncherDemo\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\t//tag::user_guide[]\n\t\t\t\tNamespacedHierarchicalStore store = session.getStore(); // <1>\n\t\t\t\tstore.computeIfAbsent(Namespace.GLOBAL, \"httpServer\", key -> { // <2>\n\t\t\t\t\tInetSocketAddress address = new InetSocketAddress(getLoopbackAddress(), 0);\n\t\t\t\t\tHttpServer server;\n\t\t\t\t\ttry {\n\t\t\t\t\t\tserver = HttpServer.create(address, 0);\n\t\t\t\t\t}\n\t\t\t\t\tcatch (IOException e) {\n\t\t\t\t\t\tthrow new UncheckedIOException(\"Failed to start HTTP server\", e);\n\t\t\t\t\t}\n\t\t\t\t\tserver.createContext(\"/test\", exchange -> {\n\t\t\t\t\t\texchange.sendResponseHeaders(204, -1);\n\t\t\t\t\t\texchange.close();\n\t\t\t\t\t});\n\t\t\t\t\tExecutorService executorService = Executors.newCachedThreadPool();\n\t\t\t\t\tserver.setExecutor(executorService);\n\t\t\t\t\tserver.start(); // <3>\n\n\t\t\t\t\treturn new CloseableHttpServer(server, executorService);\n\t\t\t\t});\n\t\t\t}\n\t\t});\n\t}\n\n}\n//end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/session/HttpTests.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.session;\n\n//tag::user_guide[]\nimport static org.junit.jupiter.api.Assertions.assertEquals;\n\nimport java.io.IOException;\nimport java.net.HttpURLConnection;\nimport java.net.URI;\nimport java.net.URL;\n\nimport com.sun.net.httpserver.HttpServer;\n\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.extension.ExtendWith;\nimport org.junit.jupiter.api.extension.ExtensionContext;\nimport org.junit.jupiter.api.extension.ParameterContext;\nimport org.junit.jupiter.api.extension.ParameterResolver;\n\n@ExtendWith(HttpServerParameterResolver.class)\nclass HttpTests {\n\n\t@Test\n\tvoid respondsWith204(HttpServer server) throws IOException {\n\t\tString host = server.getAddress().getHostString(); // <2>\n\t\tint port = server.getAddress().getPort(); // <3>\n\t\tURL url = URI.create(\"http://\" + host + \":\" + port + \"/test\").toURL();\n\n\t\tHttpURLConnection connection = (HttpURLConnection) url.openConnection();\n\t\tconnection.setRequestMethod(\"GET\");\n\t\tint responseCode = connection.getResponseCode(); // <4>\n\n\t\tassertEquals(204, responseCode); // <5>\n\t}\n}\n\nclass HttpServerParameterResolver implements ParameterResolver {\n\t@Override\n\tpublic boolean supportsParameter(ParameterContext parameterContext, ExtensionContext extensionContext) {\n\t\treturn HttpServer.class.equals(parameterContext.getParameter().getType());\n\t}\n\n\t//end::user_guide[]\n\t@SuppressWarnings(\"DataFlowIssue\")\n\t//tag::user_guide[]\n\t@Override\n\tpublic Object resolveParameter(ParameterContext parameterContext, ExtensionContext extensionContext) {\n\t\treturn extensionContext\n\t\t\t\t// tag::custom_line_break[]\n\t\t\t\t.getStore(ExtensionContext.Namespace.GLOBAL)\n\t\t\t\t// tag::custom_line_break[]\n\t\t\t\t.get(\"httpServer\", CloseableHttpServer.class) // <1>\n\t\t\t\t.getServer();\n\t}\n}\n//end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/session/package-info.java",
"content": "\n@NullMarked\npackage example.session;\n\nimport org.jspecify.annotations.NullMarked;\n"
},
{
"path": "documentation/src/test/java/example/sharedresources/ChildrenSharedResourcesDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.sharedresources;\n\nimport static org.junit.jupiter.api.parallel.ExecutionMode.CONCURRENT;\nimport static org.junit.jupiter.api.parallel.ResourceAccessMode.READ;\nimport static org.junit.jupiter.api.parallel.ResourceAccessMode.READ_WRITE;\nimport static org.junit.jupiter.api.parallel.ResourceLockTarget.CHILDREN;\n\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.parallel.Execution;\nimport org.junit.jupiter.api.parallel.ResourceLock;\n\n// tag::user_guide[]\n@Execution(CONCURRENT)\n@ResourceLock(value = \"a\", mode = READ, target = CHILDREN)\npublic class ChildrenSharedResourcesDemo {\n\n\t@ResourceLock(value = \"a\", mode = READ_WRITE)\n\t@Test\n\tvoid test1() throws InterruptedException {\n\t\tThread.sleep(2000L);\n\t}\n\n\t@Test\n\tvoid test2() throws InterruptedException {\n\t\tThread.sleep(2000L);\n\t}\n\n\t@Test\n\tvoid test3() throws InterruptedException {\n\t\tThread.sleep(2000L);\n\t}\n\n\t@Test\n\tvoid test4() throws InterruptedException {\n\t\tThread.sleep(2000L);\n\t}\n\n\t@Test\n\tvoid test5() throws InterruptedException {\n\t\tThread.sleep(2000L);\n\t}\n\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/sharedresources/DynamicSharedResourcesDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.sharedresources;\n\nimport static org.junit.jupiter.api.Assertions.assertEquals;\nimport static org.junit.jupiter.api.Assertions.assertNull;\nimport static org.junit.jupiter.api.parallel.ExecutionMode.CONCURRENT;\nimport static org.junit.jupiter.api.parallel.ResourceAccessMode.READ;\nimport static org.junit.jupiter.api.parallel.ResourceAccessMode.READ_WRITE;\nimport static org.junit.jupiter.api.parallel.Resources.SYSTEM_PROPERTIES;\n\nimport java.lang.reflect.Method;\nimport java.util.List;\nimport java.util.Properties;\nimport java.util.Set;\n\nimport org.junit.jupiter.api.AfterEach;\nimport org.junit.jupiter.api.BeforeEach;\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.parallel.Execution;\nimport org.junit.jupiter.api.parallel.ResourceAccessMode;\nimport org.junit.jupiter.api.parallel.ResourceLock;\nimport org.junit.jupiter.api.parallel.ResourceLocksProvider;\n\n// tag::user_guide[]\n@Execution(CONCURRENT)\n@ResourceLock(providers = DynamicSharedResourcesDemo.Provider.class)\nclass DynamicSharedResourcesDemo {\n\n\tprivate Properties backup;\n\n\t@BeforeEach\n\tvoid backup() {\n\t\tbackup = new Properties();\n\t\tbackup.putAll(System.getProperties());\n\t}\n\n\t@AfterEach\n\tvoid restore() {\n\t\tSystem.setProperties(backup);\n\t}\n\n\t@Test\n\tvoid customPropertyIsNotSetByDefault() {\n\t\tassertNull(System.getProperty(\"my.prop\"));\n\t}\n\n\t@Test\n\tvoid canSetCustomPropertyToApple() {\n\t\tSystem.setProperty(\"my.prop\", \"apple\");\n\t\tassertEquals(\"apple\", System.getProperty(\"my.prop\"));\n\t}\n\n\t@Test\n\tvoid canSetCustomPropertyToBanana() {\n\t\tSystem.setProperty(\"my.prop\", \"banana\");\n\t\tassertEquals(\"banana\", System.getProperty(\"my.prop\"));\n\t}\n\n\tstatic class Provider implements ResourceLocksProvider {\n\n\t\t@Override\n\t\tpublic Set provideForMethod(List> enclosingInstanceTypes, Class testClass,\n\t\t\t\tMethod testMethod) {\n\t\t\tResourceAccessMode mode = testMethod.getName().startsWith(\"canSet\") ? READ_WRITE : READ;\n\t\t\treturn Set.of(new Lock(SYSTEM_PROPERTIES, mode));\n\t\t}\n\t}\n\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/sharedresources/SharedResourceDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.sharedresources;\n\nimport static org.junit.jupiter.api.Assertions.assertSame;\nimport static org.junit.jupiter.api.Assertions.assertTrue;\nimport static org.junit.platform.engine.discovery.DiscoverySelectors.selectPackage;\nimport static org.junit.platform.launcher.core.LauncherDiscoveryRequestBuilder.discoveryRequest;\n\nimport example.FirstCustomEngine;\nimport example.SecondCustomEngine;\n\nimport org.junit.jupiter.api.Test;\nimport org.junit.platform.launcher.Launcher;\nimport org.junit.platform.launcher.LauncherDiscoveryRequest;\nimport org.junit.platform.launcher.core.LauncherConfig;\nimport org.junit.platform.launcher.core.LauncherFactory;\n\nclass SharedResourceDemo {\n\n\t@SuppressWarnings(\"DataFlowIssue\")\n\t//tag::user_guide[]\n\t@Test\n\tvoid runBothCustomEnginesTest() {\n\t\tFirstCustomEngine firstCustomEngine = new FirstCustomEngine();\n\t\tSecondCustomEngine secondCustomEngine = new SecondCustomEngine();\n\n\t\tLauncherConfig launcherConfig = LauncherConfig.builder()\n\t\t\t\t// tag::custom_line_break[]\n\t\t\t\t.addTestEngines(firstCustomEngine, secondCustomEngine)\n\t\t\t\t// tag::custom_line_break[]\n\t\t\t\t.enableTestEngineAutoRegistration(false)\n\t\t\t\t// tag::custom_line_break[]\n\t\t\t\t.build();\n\n\t\tLauncherDiscoveryRequest discoveryRequest = discoveryRequest()\n\t\t\t\t// tag::custom_line_break[]\n\t\t\t\t.selectors(selectPackage(\"com.example.mytests\"))\n\t\t\t\t// tag::custom_line_break[]\n\t\t\t\t.build();\n\n\t\tLauncher launcher = LauncherFactory.create(launcherConfig);\n\t\tlauncher.execute(discoveryRequest);\n\n\t\tassertSame(firstCustomEngine.getSocket(), secondCustomEngine.getSocket());\n\t\tassertTrue(firstCustomEngine.getSocket().isClosed(), \"socket should be closed\");\n\t}\n\t//end::user_guide[]\n\n}\n"
},
{
"path": "documentation/src/test/java/example/sharedresources/StaticSharedResourcesDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.sharedresources;\n\nimport static org.junit.jupiter.api.Assertions.assertEquals;\nimport static org.junit.jupiter.api.Assertions.assertNull;\nimport static org.junit.jupiter.api.parallel.ExecutionMode.CONCURRENT;\nimport static org.junit.jupiter.api.parallel.ResourceAccessMode.READ;\nimport static org.junit.jupiter.api.parallel.ResourceAccessMode.READ_WRITE;\nimport static org.junit.jupiter.api.parallel.Resources.SYSTEM_PROPERTIES;\n\nimport java.util.Properties;\n\nimport org.junit.jupiter.api.AfterEach;\nimport org.junit.jupiter.api.BeforeEach;\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.parallel.Execution;\nimport org.junit.jupiter.api.parallel.ResourceLock;\n\n// tag::user_guide[]\n@Execution(CONCURRENT)\nclass StaticSharedResourcesDemo {\n\n\tprivate Properties backup;\n\n\t@BeforeEach\n\tvoid backup() {\n\t\tbackup = new Properties();\n\t\tbackup.putAll(System.getProperties());\n\t}\n\n\t@AfterEach\n\tvoid restore() {\n\t\tSystem.setProperties(backup);\n\t}\n\n\t@Test\n\t@ResourceLock(value = SYSTEM_PROPERTIES, mode = READ)\n\tvoid customPropertyIsNotSetByDefault() {\n\t\tassertNull(System.getProperty(\"my.prop\"));\n\t}\n\n\t@Test\n\t@ResourceLock(value = SYSTEM_PROPERTIES, mode = READ_WRITE)\n\tvoid canSetCustomPropertyToApple() {\n\t\tSystem.setProperty(\"my.prop\", \"apple\");\n\t\tassertEquals(\"apple\", System.getProperty(\"my.prop\"));\n\t}\n\n\t@Test\n\t@ResourceLock(value = SYSTEM_PROPERTIES, mode = READ_WRITE)\n\tvoid canSetCustomPropertyToBanana() {\n\t\tSystem.setProperty(\"my.prop\", \"banana\");\n\t\tassertEquals(\"banana\", System.getProperty(\"my.prop\"));\n\t}\n\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/sharedresources/package-info.java",
"content": "\n@NullMarked\npackage example.sharedresources;\n\nimport org.jspecify.annotations.NullMarked;\n"
},
{
"path": "documentation/src/test/java/example/testinterface/TestInterfaceDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.testinterface;\n\nimport static org.junit.jupiter.api.Assertions.assertEquals;\n\nimport org.junit.jupiter.api.Test;\n\n// @formatter:off\n// tag::user_guide[]\nclass TestInterfaceDemo implements TestLifecycleLogger,\n\t\tTimeExecutionLogger, TestInterfaceDynamicTestsDemo {\n\n\t@Test\n\tvoid isEqualValue() {\n\t\tassertEquals(1, \"a\".length(), \"is always equal\");\n\t}\n\n}\n// end::user_guide[]\n// @formatter:on\n"
},
{
"path": "documentation/src/test/java/example/testinterface/TestInterfaceDynamicTestsDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.testinterface;\n\nimport static example.util.StringUtils.isPalindrome;\nimport static org.junit.jupiter.api.Assertions.assertTrue;\nimport static org.junit.jupiter.api.DynamicTest.dynamicTest;\n\nimport java.util.stream.Stream;\n\nimport org.junit.jupiter.api.DynamicTest;\nimport org.junit.jupiter.api.TestFactory;\n\n// @formatter:off\n// tag::user_guide[]\ninterface TestInterfaceDynamicTestsDemo {\n\n\t@TestFactory\n\tdefault Stream dynamicTestsForPalindromes() {\n\t\treturn Stream.of(\"racecar\", \"radar\", \"mom\", \"dad\")\n\t\t\t.map(text -> dynamicTest(text, () -> assertTrue(isPalindrome(text))));\n\t}\n\n}\n// end::user_guide[]\n// @formatter:on\n"
},
{
"path": "documentation/src/test/java/example/testinterface/TestLifecycleLogger.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.testinterface;\n\nimport java.util.logging.Logger;\n\nimport org.junit.jupiter.api.AfterAll;\nimport org.junit.jupiter.api.AfterEach;\nimport org.junit.jupiter.api.BeforeAll;\nimport org.junit.jupiter.api.BeforeEach;\nimport org.junit.jupiter.api.TestInfo;\nimport org.junit.jupiter.api.TestInstance;\nimport org.junit.jupiter.api.TestInstance.Lifecycle;\n\n// @formatter:off\n// tag::user_guide[]\n@TestInstance(Lifecycle.PER_CLASS)\ninterface TestLifecycleLogger {\n\n\tLogger logger = Logger.getLogger(TestLifecycleLogger.class.getName());\n\n\t@BeforeAll\n\tdefault void beforeAllTests() {\n\t\tlogger.info(\"Before all tests\");\n\t}\n\n\t@AfterAll\n\tdefault void afterAllTests() {\n\t\tlogger.info(\"After all tests\");\n\t}\n\n\t@BeforeEach\n\tdefault void beforeEachTest(TestInfo testInfo) {\n\t\tlogger.info(() -> \"About to execute [%s]\".formatted(\n\t\t\ttestInfo.getDisplayName()));\n\t}\n\n\t@AfterEach\n\tdefault void afterEachTest(TestInfo testInfo) {\n\t\tlogger.info(() -> \"Finished executing [%s]\".formatted(\n\t\t\ttestInfo.getDisplayName()));\n\t}\n\n}\n// end::user_guide[]\n// @formatter:on\n"
},
{
"path": "documentation/src/test/java/example/testinterface/TimeExecutionLogger.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.testinterface;\n\nimport example.timing.TimingExtension;\n\nimport org.junit.jupiter.api.Tag;\nimport org.junit.jupiter.api.extension.ExtendWith;\n\n//tag::user_guide[]\n@Tag(\"timed\")\n@ExtendWith(TimingExtension.class)\ninterface TimeExecutionLogger {\n}\n//end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/testinterface/package-info.java",
"content": "\n@NullMarked\npackage example.testinterface;\n\nimport org.jspecify.annotations.NullMarked;\n"
},
{
"path": "documentation/src/test/java/example/testkit/EngineTestKitAllEventsDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.testkit;\n\n// @formatter:off\n// tag::user_guide[]\n\nimport static org.junit.platform.engine.discovery.DiscoverySelectors.selectClass;\nimport static org.junit.platform.testkit.engine.EventConditions.abortedWithReason;\nimport static org.junit.platform.testkit.engine.EventConditions.container;\nimport static org.junit.platform.testkit.engine.EventConditions.engine;\nimport static org.junit.platform.testkit.engine.EventConditions.event;\nimport static org.junit.platform.testkit.engine.EventConditions.finishedSuccessfully;\nimport static org.junit.platform.testkit.engine.EventConditions.finishedWithFailure;\nimport static org.junit.platform.testkit.engine.EventConditions.skippedWithReason;\nimport static org.junit.platform.testkit.engine.EventConditions.started;\nimport static org.junit.platform.testkit.engine.EventConditions.test;\nimport static org.junit.platform.testkit.engine.TestExecutionResultConditions.instanceOf;\nimport static org.junit.platform.testkit.engine.TestExecutionResultConditions.message;\n\nimport java.io.StringWriter;\nimport java.io.Writer;\n\nimport example.ExampleTestCase;\n\nimport org.junit.jupiter.api.Test;\nimport org.junit.platform.testkit.engine.EngineTestKit;\nimport org.opentest4j.TestAbortedException;\n\nclass EngineTestKitAllEventsDemo {\n\n\t@Test\n\tvoid verifyAllJupiterEvents() {\n\t\tWriter writer = // create a java.io.Writer for debug output\n\t\t// end::user_guide[]\n\t\t\t\t// For the demo, we are swallowing the debug output.\n\t\t\t\tnew StringWriter();\n\t\t// tag::user_guide[]\n\n\t\tEngineTestKit.engine(\"junit-jupiter\") // <1>\n\t\t\t.selectors(selectClass(ExampleTestCase.class)) // <2>\n\t\t\t.execute() // <3>\n\t\t\t.allEvents() // <4>\n\t\t\t.debug(writer) // <5>\n\t\t\t.assertEventsMatchExactly( // <6>\n\t\t\t\tevent(engine(), started()),\n\t\t\t\tevent(container(ExampleTestCase.class), started()),\n\t\t\t\tevent(test(\"skippedTest\"), skippedWithReason(\"for demonstration purposes\")),\n\t\t\t\tevent(test(\"succeedingTest\"), started()),\n\t\t\t\tevent(test(\"succeedingTest\"), finishedSuccessfully()),\n\t\t\t\tevent(test(\"abortedTest\"), started()),\n\t\t\t\tevent(test(\"abortedTest\"),\n\t\t\t\t\tabortedWithReason(instanceOf(TestAbortedException.class),\n\t\t\t\t\t\tmessage(m -> m.contains(\"abc does not contain Z\")))),\n\t\t\t\tevent(test(\"failingTest\"), started()),\n\t\t\t\tevent(test(\"failingTest\"), finishedWithFailure(\n\t\t\t\t\tinstanceOf(ArithmeticException.class), message(it -> it.endsWith(\"by zero\")))),\n\t\t\t\tevent(container(ExampleTestCase.class), finishedSuccessfully()),\n\t\t\t\tevent(engine(), finishedSuccessfully()));\n\t}\n\n}\n// end::user_guide[]\n// @formatter:on\n"
},
{
"path": "documentation/src/test/java/example/testkit/EngineTestKitDiscoveryDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.testkit;\n\n// tag::user_guide[]\nimport static java.util.Collections.emptyList;\nimport static org.junit.jupiter.api.Assertions.assertEquals;\nimport static org.junit.platform.engine.discovery.DiscoverySelectors.selectClass;\n\nimport example.ExampleTestCase;\n\nimport org.junit.jupiter.api.Test;\nimport org.junit.platform.testkit.engine.EngineDiscoveryResults;\nimport org.junit.platform.testkit.engine.EngineTestKit;\n\nclass EngineTestKitDiscoveryDemo {\n\n\t@Test\n\tvoid verifyJupiterDiscovery() {\n\t\tEngineDiscoveryResults results = EngineTestKit.engine(\"junit-jupiter\") // <1>\n\t\t\t\t.selectors(selectClass(ExampleTestCase.class)) // <2>\n\t\t\t\t.discover(); // <3>\n\n\t\tassertEquals(\"JUnit Jupiter\", results.getEngineDescriptor().getDisplayName()); // <4>\n\t\tassertEquals(emptyList(), results.getDiscoveryIssues()); // <5>\n\t}\n\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/testkit/EngineTestKitFailedMethodDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.testkit;\n\n// @formatter:off\n// tag::user_guide[]\n\nimport static org.junit.platform.engine.discovery.DiscoverySelectors.selectClass;\nimport static org.junit.platform.testkit.engine.EventConditions.event;\nimport static org.junit.platform.testkit.engine.EventConditions.finishedWithFailure;\nimport static org.junit.platform.testkit.engine.EventConditions.test;\nimport static org.junit.platform.testkit.engine.TestExecutionResultConditions.instanceOf;\nimport static org.junit.platform.testkit.engine.TestExecutionResultConditions.message;\n\nimport example.ExampleTestCase;\n\nimport org.junit.jupiter.api.Test;\nimport org.junit.platform.testkit.engine.EngineTestKit;\n\nclass EngineTestKitFailedMethodDemo {\n\n\t@Test\n\tvoid verifyJupiterMethodFailed() {\n\t\tEngineTestKit.engine(\"junit-jupiter\") // <1>\n\t\t\t.selectors(selectClass(ExampleTestCase.class)) // <2>\n\t\t\t.execute() // <3>\n\t\t\t.testEvents() // <4>\n\t\t\t.assertThatEvents().haveExactly(1, // <5>\n\t\t\t\tevent(test(\"failingTest\"),\n\t\t\t\t\tfinishedWithFailure(\n\t\t\t\t\t\tinstanceOf(ArithmeticException.class), message(it -> it.endsWith(\"by zero\")))));\n\t}\n\n}\n// end::user_guide[]\n// @formatter:on\n"
},
{
"path": "documentation/src/test/java/example/testkit/EngineTestKitSkippedMethodDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.testkit;\n\n// @formatter:off\n// tag::user_guide[]\n\nimport static org.junit.platform.engine.discovery.DiscoverySelectors.selectMethod;\nimport static org.junit.platform.testkit.engine.EventConditions.event;\nimport static org.junit.platform.testkit.engine.EventConditions.skippedWithReason;\nimport static org.junit.platform.testkit.engine.EventConditions.test;\n\nimport example.ExampleTestCase;\n\nimport org.junit.jupiter.api.Test;\nimport org.junit.platform.testkit.engine.EngineTestKit;\nimport org.junit.platform.testkit.engine.Events;\n\nclass EngineTestKitSkippedMethodDemo {\n\n\t@Test\n\tvoid verifyJupiterMethodWasSkipped() {\n\t\tString methodName = \"skippedTest\";\n\n\t\tEvents testEvents = EngineTestKit // <5>\n\t\t\t.engine(\"junit-jupiter\") // <1>\n\t\t\t.selectors(selectMethod(ExampleTestCase.class, methodName)) // <2>\n\t\t\t.execute() // <3>\n\t\t\t.testEvents(); // <4>\n\n\t\ttestEvents.assertStatistics(stats -> stats.skipped(1)); // <6>\n\n\t\ttestEvents.assertThatEvents() // <7>\n\t\t\t.haveExactly(1, event(test(methodName),\n\t\t\t\tskippedWithReason(\"for demonstration purposes\")));\n\t}\n\n}\n// end::user_guide[]\n// @formatter:on\n"
},
{
"path": "documentation/src/test/java/example/testkit/EngineTestKitStatisticsDemo.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.testkit;\n\n// @formatter:off\n// tag::user_guide[]\n\nimport static org.junit.platform.engine.discovery.DiscoverySelectors.selectClass;\n\nimport example.ExampleTestCase;\n\nimport org.junit.jupiter.api.Test;\nimport org.junit.platform.testkit.engine.EngineTestKit;\n\nclass EngineTestKitStatisticsDemo {\n\n\t@Test\n\tvoid verifyJupiterContainerStats() {\n\t\tEngineTestKit\n\t\t\t.engine(\"junit-jupiter\") // <1>\n\t\t\t.selectors(selectClass(ExampleTestCase.class)) // <2>\n\t\t\t.execute() // <3>\n\t\t\t.containerEvents() // <4>\n\t\t\t.assertStatistics(stats -> stats.started(2).succeeded(2)); // <5>\n\t}\n\n\t@Test\n\tvoid verifyJupiterTestStats() {\n\t\tEngineTestKit\n\t\t\t.engine(\"junit-jupiter\") // <1>\n\t\t\t.selectors(selectClass(ExampleTestCase.class)) // <2>\n\t\t\t.execute() // <3>\n\t\t\t.testEvents() // <6>\n\t\t\t.assertStatistics(stats ->\n\t\t\t\tstats.skipped(1).started(3).succeeded(1).aborted(1).failed(1)); // <7>\n\t}\n\n}\n// end::user_guide[]\n// @formatter:on\n"
},
{
"path": "documentation/src/test/java/example/testkit/package-info.java",
"content": "\n@NullMarked\npackage example.testkit;\n\nimport org.jspecify.annotations.NullMarked;\n"
},
{
"path": "documentation/src/test/java/example/timing/TimingExtension.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.timing;\n\n// tag::user_guide[]\nimport java.lang.reflect.Method;\nimport java.util.logging.Logger;\n\nimport org.junit.jupiter.api.extension.AfterTestExecutionCallback;\nimport org.junit.jupiter.api.extension.BeforeTestExecutionCallback;\nimport org.junit.jupiter.api.extension.ExtensionContext;\nimport org.junit.jupiter.api.extension.ExtensionContext.Namespace;\nimport org.junit.jupiter.api.extension.ExtensionContext.Store;\n\n// end::user_guide[]\n/**\n * Simple extension that times the execution of test methods and\n * logs the results at {@code INFO} level.\n *\n * @since 5.0\n */\n// @formatter:off\n// tag::user_guide[]\npublic class TimingExtension implements BeforeTestExecutionCallback, AfterTestExecutionCallback {\n\n\tprivate static final Logger logger = Logger.getLogger(TimingExtension.class.getName());\n\n\tprivate static final String START_TIME = \"start time\";\n\n\t@Override\n\tpublic void beforeTestExecution(ExtensionContext context) {\n\t\tgetStore(context).put(START_TIME, System.currentTimeMillis());\n\t}\n\n\t//end::user_guide[]\n\t@SuppressWarnings(\"DataFlowIssue\")\n\t//tag::user_guide[]\n\t@Override\n\tpublic void afterTestExecution(ExtensionContext context) {\n\t\tMethod testMethod = context.getRequiredTestMethod();\n\t\tlong startTime = getStore(context).remove(START_TIME, long.class);\n\t\tlong duration = System.currentTimeMillis() - startTime;\n\n\t\tlogger.info(() ->\n\t\t\t\"Method [%s] took %s ms.\".formatted(testMethod.getName(), duration));\n\t}\n\n\tprivate Store getStore(ExtensionContext context) {\n\t\treturn context.getStore(Namespace.create(getClass(), context.getRequiredTestMethod()));\n\t}\n\n}\n// end::user_guide[]\n// @formatter:on\n"
},
{
"path": "documentation/src/test/java/example/timing/TimingExtensionTests.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.timing;\n\nimport org.junit.jupiter.api.Test;\nimport org.junit.jupiter.api.extension.ExtendWith;\n\n/**\n * Tests that demonstrate the example {@link TimingExtension}.\n *\n * @since 5.0\n */\n// tag::user_guide[]\n@ExtendWith(TimingExtension.class)\nclass TimingExtensionTests {\n\n\t@Test\n\tvoid sleep20ms() throws Exception {\n\t\tThread.sleep(20);\n\t}\n\n\t@Test\n\tvoid sleep50ms() throws Exception {\n\t\tThread.sleep(50);\n\t}\n\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/java/example/timing/package-info.java",
"content": "\n@NullMarked\npackage example.timing;\n\nimport org.jspecify.annotations.NullMarked;\n"
},
{
"path": "documentation/src/test/java/extensions/DisabledOnOpenJ9.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage extensions;\n\nimport java.lang.annotation.ElementType;\nimport java.lang.annotation.Retention;\nimport java.lang.annotation.RetentionPolicy;\nimport java.lang.annotation.Target;\n\nimport org.junit.jupiter.api.condition.DisabledIfSystemProperty;\n\n@Target(ElementType.METHOD)\n@Retention(RetentionPolicy.RUNTIME)\n@DisabledIfSystemProperty(named = \"java.vm.vendor\", matches = \".*OpenJ9.*\")\npublic @interface DisabledOnOpenJ9 {\n}\n"
},
{
"path": "documentation/src/test/java/extensions/ExpectToFail.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage extensions;\n\nimport static org.junit.jupiter.api.Assertions.assertNotNull;\n\nimport java.lang.annotation.ElementType;\nimport java.lang.annotation.Retention;\nimport java.lang.annotation.RetentionPolicy;\nimport java.lang.annotation.Target;\n\nimport org.junit.jupiter.api.extension.AfterEachCallback;\nimport org.junit.jupiter.api.extension.ExtendWith;\nimport org.junit.jupiter.api.extension.ExtensionContext;\nimport org.junit.jupiter.api.extension.ExtensionContext.Namespace;\nimport org.junit.jupiter.api.extension.ExtensionContext.Store;\nimport org.junit.jupiter.api.extension.TestExecutionExceptionHandler;\n\n@Target(ElementType.METHOD)\n@Retention(RetentionPolicy.RUNTIME)\n@ExtendWith(ExpectToFail.Extension.class)\npublic @interface ExpectToFail {\n\n\tclass Extension implements TestExecutionExceptionHandler, AfterEachCallback {\n\n\t\tprivate static final String KEY = \"exception\";\n\n\t\t@Override\n\t\tpublic void handleTestExecutionException(ExtensionContext context, Throwable throwable) throws Throwable {\n\t\t\tgetExceptionStore(context).put(KEY, throwable);\n\t\t}\n\n\t\t@Override\n\t\tpublic void afterEach(ExtensionContext context) throws Exception {\n\t\t\tassertNotNull(getExceptionStore(context).get(KEY), \"Test should have failed\");\n\t\t}\n\n\t\tprivate Store getExceptionStore(ExtensionContext context) {\n\t\t\treturn context.getStore(Namespace.create(getClass(), context.getRequiredTestMethod()));\n\t\t}\n\t}\n\n}\n"
},
{
"path": "documentation/src/test/java/extensions/package-info.java",
"content": "\n@NullMarked\npackage extensions;\n\nimport org.jspecify.annotations.NullMarked;\n"
},
{
"path": "documentation/src/test/kotlin/example/FibonacciCalculator.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example\n\nclass FibonacciCalculator {\n private val fibonacci =\n sequence {\n yield(0) // 0th Fibonacci number\n yield(1) // first Fibonacci number\n var cur = 1\n var next = 1\n while (true) {\n yield(next) // next Fibonacci number\n val tmp = cur + next\n cur = next\n next = tmp\n }\n }\n\n fun fib(fibonacciNumber: Int) = fibonacci.elementAt(fibonacciNumber)\n}\n"
},
{
"path": "documentation/src/test/kotlin/example/KotlinAssertionsDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example\n\n// tag::user_guide[]\n\nimport example.domain.Person\nimport example.util.Calculator\nimport org.junit.jupiter.api.Assertions.assertEquals\nimport org.junit.jupiter.api.Assertions.assertTrue\nimport org.junit.jupiter.api.Tag\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.assertAll\nimport org.junit.jupiter.api.assertDoesNotThrow\nimport org.junit.jupiter.api.assertInstanceOf\nimport org.junit.jupiter.api.assertNotNull\nimport org.junit.jupiter.api.assertThrows\nimport org.junit.jupiter.api.assertTimeout\nimport org.junit.jupiter.api.assertTimeoutPreemptively\nimport java.time.Duration\n\nclass KotlinAssertionsDemo {\n private val person = Person(\"Jane\", \"Doe\")\n private val people = setOf(person, Person(\"John\", \"Doe\"))\n\n @Test\n fun `exception absence testing`() {\n val calculator = Calculator()\n val result =\n assertDoesNotThrow(\"Should not throw an exception\") {\n calculator.divide(0, 1)\n }\n assertEquals(0, result)\n }\n\n // end::user_guide[]\n @extensions.DisabledOnOpenJ9\n // tag::user_guide[]\n @Test\n fun `expected exception testing`() {\n val calculator = Calculator()\n val exception =\n assertThrows (\"Should throw an exception\") {\n calculator.divide(1, 0)\n }\n assertEquals(\"/ by zero\", exception.message)\n }\n\n @Test\n fun `grouped assertions`() {\n assertAll(\n \"Person properties\",\n { assertEquals(\"Jane\", person.firstName) },\n { assertEquals(\"Doe\", person.lastName) }\n )\n }\n\n @Test\n fun `grouped assertions from a stream`() {\n assertAll(\n \"People with first name starting with J\",\n people\n .stream()\n .map {\n // This mapping returns Stream<() -> Unit>\n { assertTrue(it.firstName.startsWith(\"J\")) }\n }\n )\n }\n\n @Test\n fun `grouped assertions from a collection`() {\n assertAll(\n \"People with last name of Doe\",\n people.map { { assertEquals(\"Doe\", it.lastName) } }\n )\n }\n\n // end::user_guide[]\n @Tag(\"timeout\")\n // tag::user_guide[]\n @Test\n fun `timeout not exceeded testing`() {\n val fibonacciCalculator = FibonacciCalculator()\n val result =\n assertTimeout(Duration.ofMillis(1000)) {\n fibonacciCalculator.fib(14)\n }\n assertEquals(377, result)\n }\n\n // end::user_guide[]\n @Tag(\"timeout\")\n @extensions.ExpectToFail\n // tag::user_guide[]\n @Test\n fun `timeout exceeded with preemptive termination`() {\n // The following assertion fails with an error message similar to:\n // execution timed out after 10 ms\n assertTimeoutPreemptively(Duration.ofMillis(10)) {\n // Simulate task that takes more than 10 ms.\n Thread.sleep(100)\n }\n }\n\n @Test\n fun `assertNotNull with a smart cast`() {\n val nullablePerson: Person? = person\n\n assertNotNull(nullablePerson)\n\n // The compiler smart casts nullablePerson to a non-nullable object.\n // The safe call operator (?.) isn't required.\n assertEquals(person.firstName, nullablePerson.firstName)\n assertEquals(person.lastName, nullablePerson.lastName)\n }\n\n @Test\n fun `assertInstanceOf with a smart cast`() {\n val maybePerson: Any = person\n\n assertInstanceOf(maybePerson)\n\n // The compiler smart casts maybePerson to a Person object,\n // allowing to access the Person properties.\n assertEquals(person.firstName, maybePerson.firstName)\n assertEquals(person.lastName, maybePerson.lastName)\n }\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/KotlinCoroutinesDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example\n\n// tag::user_guide[]\nimport org.junit.jupiter.api.BeforeEach\nimport org.junit.jupiter.api.Test\n\n// end::user_guide[]\n// @formatter:off\n@Suppress(\"JUnitMalformedDeclaration\")\n// tag::user_guide[]\nclass KotlinCoroutinesDemo {\n // end::user_guide[]\n // @formatter:on\n // tag::user_guide[]\n @BeforeEach\n fun regularSetUp() {\n }\n\n @BeforeEach\n suspend fun coroutineSetUp() {\n }\n\n @Test\n fun regularTest() {\n }\n\n @Test\n suspend fun coroutineTest() {\n }\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/KotlinCoroutinesRunTestDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example\n\n// tag::user_guide[]\nimport kotlinx.coroutines.test.runTest\nimport org.junit.jupiter.api.Test\n\nclass KotlinCoroutinesRunTestDemo {\n // end::user_guide[]\n // @formatter:off\n // tag::user_guide[]\n @Test\n fun coroutineTestUsingRunTest() = runTest {\n // ...\n }\n // end::user_guide[]\n // @formatter:on\n // tag::user_guide[]\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/AssumptionsDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin\n\n// tag::user_guide[]\n\nimport example.util.Calculator\nimport org.junit.jupiter.api.Assertions.assertEquals\nimport org.junit.jupiter.api.Assumptions.assumeTrue\nimport org.junit.jupiter.api.Assumptions.assumingThat\nimport org.junit.jupiter.api.Test\n\nclass AssumptionsDemo {\n private val calculator = Calculator()\n\n @Test\n fun testOnlyOnCiServer() {\n assumeTrue(System.getenv(\"ENV\") == \"CI\")\n // remainder of test\n }\n\n @Test\n fun testOnlyOnDeveloperWorkstation() {\n assumeTrue(System.getenv(\"ENV\") == \"DEV\") {\n \"Aborting test: not on developer workstation\"\n }\n // remainder of test\n }\n\n @Test\n fun testInAllEnvironments() {\n assumingThat(System.getenv(\"ENV\") == \"CI\") {\n // perform these assertions only on the CI server\n assertEquals(2, calculator.divide(4, 2))\n }\n\n // perform these assertions in all environments\n assertEquals(42, calculator.multiply(6, 7))\n }\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/AutoCloseDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin\n\nimport example.registration.WebClient\nimport org.junit.jupiter.api.Assertions.assertEquals\nimport org.junit.jupiter.api.AutoClose\nimport org.junit.jupiter.api.Test\n\n// tag::user_guide_example[]\nclass AutoCloseDemo {\n @AutoClose // <1>\n val webClient = WebClient() // <2>\n\n val serverUrl = // specify server URL ...\n // end::user_guide_example[]\n \"https://localhost\"\n // tag::user_guide_example[]\n\n @Test\n fun getProductList() {\n // Use WebClient to connect to web server and verify response\n assertEquals(200, webClient.get(\"$serverUrl/products\").responseStatus)\n }\n}\n// end::user_guide_example[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/ConditionalTestExecutionDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin\n\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.condition.DisabledForJreRange\nimport org.junit.jupiter.api.condition.DisabledIf\nimport org.junit.jupiter.api.condition.DisabledIfEnvironmentVariable\nimport org.junit.jupiter.api.condition.DisabledIfSystemProperty\nimport org.junit.jupiter.api.condition.DisabledInNativeImage\nimport org.junit.jupiter.api.condition.DisabledOnJre\nimport org.junit.jupiter.api.condition.DisabledOnOs\nimport org.junit.jupiter.api.condition.EnabledForJreRange\nimport org.junit.jupiter.api.condition.EnabledIf\nimport org.junit.jupiter.api.condition.EnabledIfEnvironmentVariable\nimport org.junit.jupiter.api.condition.EnabledIfSystemProperty\nimport org.junit.jupiter.api.condition.EnabledInNativeImage\nimport org.junit.jupiter.api.condition.EnabledOnJre\nimport org.junit.jupiter.api.condition.EnabledOnOs\nimport org.junit.jupiter.api.condition.JRE.JAVA_17\nimport org.junit.jupiter.api.condition.JRE.JAVA_18\nimport org.junit.jupiter.api.condition.JRE.JAVA_19\nimport org.junit.jupiter.api.condition.JRE.JAVA_21\nimport org.junit.jupiter.api.condition.JRE.JAVA_25\nimport org.junit.jupiter.api.condition.OS.LINUX\nimport org.junit.jupiter.api.condition.OS.MAC\nimport org.junit.jupiter.api.condition.OS.WINDOWS\n\nclass ConditionalTestExecutionDemo {\n // tag::user_guide_os[]\n @Test\n @EnabledOnOs(MAC)\n fun onlyOnMacOs() {\n // ...\n }\n\n @TestOnMac\n fun testOnMac() {\n // ...\n }\n\n @Test\n @EnabledOnOs(LINUX, MAC)\n fun onLinuxOrMac() {\n // ...\n }\n\n @Test\n @DisabledOnOs(WINDOWS)\n fun notOnWindows() {\n // ...\n }\n\n @Target(AnnotationTarget.FUNCTION)\n @Retention(AnnotationRetention.RUNTIME)\n @Test\n @EnabledOnOs(MAC)\n annotation class TestOnMac\n // end::user_guide_os[]\n\n // tag::user_guide_architecture[]\n @Test\n @EnabledOnOs(architectures = [\"aarch64\"])\n fun onAarch64() {\n // ...\n }\n\n @Test\n @DisabledOnOs(architectures = [\"x86_64\"])\n fun notOnX86_64() {\n // ...\n }\n\n @Test\n @EnabledOnOs(value = [MAC], architectures = [\"aarch64\"])\n fun onNewMacs() {\n // ...\n }\n\n @Test\n @DisabledOnOs(value = [MAC], architectures = [\"aarch64\"])\n fun notOnNewMacs() {\n // ...\n }\n // end::user_guide_architecture[]\n\n // tag::user_guide_jre[]\n @Test\n @EnabledOnJre(JAVA_17)\n fun onlyOnJava17() {\n // ...\n }\n\n @Test\n @EnabledOnJre(JAVA_17, JAVA_21)\n fun onJava17And21() {\n // ...\n }\n\n @Test\n @EnabledForJreRange(min = JAVA_21, max = JAVA_25)\n fun fromJava21To25() {\n // ...\n }\n\n @Test\n @EnabledForJreRange(min = JAVA_21)\n fun onJava21ndHigher() {\n // ...\n }\n\n @Test\n @EnabledForJreRange(max = JAVA_18)\n fun fromJava17To18() {\n // ...\n }\n\n @Test\n @DisabledOnJre(JAVA_19)\n fun notOnJava19() {\n // ...\n }\n\n @Test\n @DisabledForJreRange(min = JAVA_17, max = JAVA_17)\n fun notFromJava17To19() {\n // ...\n }\n\n @Test\n @DisabledForJreRange(min = JAVA_19)\n fun notOnJava19AndHigher() {\n // ...\n }\n\n @Test\n @DisabledForJreRange(max = JAVA_18)\n fun notFromJava17To18() {\n // ...\n }\n // end::user_guide_jre[]\n\n // tag::user_guide_jre_arbitrary_versions[]\n @Test\n @EnabledOnJre(versions = [26])\n fun onlyOnJava26() {\n // ...\n }\n\n // Can also be expressed as follows.\n // @EnabledOnJre(value = [JAVA_25], versions = [26])\n @Test\n @EnabledOnJre(versions = [25, 26])\n fun onJava25And26() {\n // ...\n }\n\n @Test\n @EnabledForJreRange(minVersion = 26)\n fun onJava26AndHigher() {\n // ...\n }\n\n // Can also be expressed as follows.\n // @EnabledForJreRange(min = JAVA_25, maxVersion = 27)\n @Test\n @EnabledForJreRange(minVersion = 25, maxVersion = 27)\n fun fromJava25To27() {\n // ...\n }\n\n @Test\n @DisabledOnJre(versions = [26])\n fun notOnJava26() {\n // ...\n }\n\n // Can also be expressed as follows.\n // @DisabledOnJre(value = [JAVA_25], versions = [26])\n @Test\n @DisabledOnJre(versions = [25, 26])\n fun notOnJava25And26() {\n // ...\n }\n\n @Test\n @DisabledForJreRange(minVersion = 26)\n fun notOnJava26AndHigher() {\n // ...\n }\n\n // Can also be expressed as follows.\n // @DisabledForJreRange(min = JAVA_25, maxVersion = 27)\n @Test\n @DisabledForJreRange(minVersion = 25, maxVersion = 27)\n fun notFromJava25To27() {\n // ...\n }\n // end::user_guide_jre_arbitrary_versions[]\n\n // tag::user_guide_native[]\n @Test\n @EnabledInNativeImage\n fun onlyWithinNativeImage() {\n // ...\n }\n\n @Test\n @DisabledInNativeImage\n fun neverWithinNativeImage() {\n // ...\n }\n // end::user_guide_native[]\n\n // tag::user_guide_system_property[]\n @Test\n @EnabledIfSystemProperty(named = \"os.arch\", matches = \".*64.*\")\n fun onlyOn64BitArchitectures() {\n // ...\n }\n\n @Test\n @DisabledIfSystemProperty(named = \"ci-server\", matches = \"true\")\n fun notOnCiServer() {\n // ...\n }\n // end::user_guide_system_property[]\n\n // tag::user_guide_environment_variable[]\n @Test\n @EnabledIfEnvironmentVariable(named = \"ENV\", matches = \"staging-server\")\n fun onlyOnStagingServer() {\n // ...\n }\n\n @Test\n @DisabledIfEnvironmentVariable(named = \"ENV\", matches = \".*development.*\")\n fun notOnDeveloperWorkstation() {\n // ...\n }\n // end::user_guide_environment_variable[]\n\n // tag::user_guide_custom[]\n @Test\n @EnabledIf(\"customCondition\")\n fun enabled() {\n // ...\n }\n\n @Test\n @DisabledIf(\"customCondition\")\n fun disabled() {\n // ...\n }\n\n fun customCondition(): Boolean = true\n // end::user_guide_custom[]\n}\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/DefaultLocaleTimezoneExtensionDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin\n\nimport org.assertj.core.api.Assertions.assertThat\nimport org.junit.jupiter.api.Nested\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.util.DefaultLocale\nimport org.junit.jupiter.api.util.DefaultTimeZone\nimport org.junit.jupiter.api.util.LocaleProvider\nimport org.junit.jupiter.api.util.TimeZoneProvider\nimport java.time.ZoneOffset\nimport java.util.Locale\nimport java.util.TimeZone\n\nclass DefaultLocaleTimezoneExtensionDemo {\n // tag::default_locale_language[]\n @Test\n @DefaultLocale(\"zh-Hant-TW\")\n fun test_with_language() {\n assertThat(Locale.getDefault()).isEqualTo(Locale.forLanguageTag(\"zh-Hant-TW\"))\n }\n // end::default_locale_language[]\n\n // tag::default_locale_language_alternatives[]\n @Test\n @DefaultLocale(language = \"en\")\n fun test_with_language_only() {\n assertThat(Locale.getDefault()).isEqualTo(Locale.Builder().setLanguage(\"en\").build())\n }\n\n @Test\n @DefaultLocale(language = \"en\", country = \"EN\")\n fun test_with_language_and_country() {\n assertThat(Locale.getDefault()).isEqualTo(\n Locale\n .Builder()\n .setLanguage(\"en\")\n .setRegion(\"EN\")\n .build()\n )\n }\n\n @Test\n @DefaultLocale(language = \"ja\", country = \"JP\", variant = \"japanese\")\n fun test_with_language_and_country_and_vairant() {\n assertThat(Locale.getDefault()).isEqualTo(\n Locale\n .Builder()\n .setLanguage(\"ja\")\n .setRegion(\"JP\")\n .setVariant(\"japanese\")\n .build()\n )\n }\n // end::default_locale_language_alternatives[]\n\n // @formatter:off\n @Nested\n // tag::default_locale_class_level[]\n @DefaultLocale(language = \"fr\")\n // end::default_locale_class_level[]\n inner\n // tag::default_locale_class_level[]\n class MyLocaleTests {\n // end::default_locale_class_level[]\n // @formatter:on\n // tag::default_locale_class_level[]\n @Test\n fun test_with_class_level_configuration() {\n assertThat(Locale.getDefault()).isEqualTo(Locale.Builder().setLanguage(\"fr\").build())\n }\n\n @Test\n @DefaultLocale(language = \"en\")\n fun test_with_method_level_configuration() {\n assertThat(Locale.getDefault()).isEqualTo(Locale.Builder().setLanguage(\"en\").build())\n }\n }\n // end::default_locale_class_level[]\n\n // tag::default_locale_with_provider[]\n @Test\n @DefaultLocale(localeProvider = EnglishProvider::class)\n fun test_with_locale_provider() {\n assertThat(Locale.getDefault()).isEqualTo(Locale.Builder().setLanguage(\"en\").build())\n }\n\n class EnglishProvider : LocaleProvider {\n override fun get(): Locale = Locale.ENGLISH\n }\n // end::default_locale_with_provider[]\n\n // tag::default_timezone_zone[]\n @Test\n @DefaultTimeZone(\"CET\")\n fun test_with_short_zone_id() {\n assertThat(TimeZone.getDefault()).isEqualTo(TimeZone.getTimeZone(\"CET\"))\n }\n\n @Test\n @DefaultTimeZone(\"Africa/Juba\")\n fun test_with_long_zone_id() {\n assertThat(TimeZone.getDefault()).isEqualTo(TimeZone.getTimeZone(\"Africa/Juba\"))\n }\n // end::default_timezone_zone[]\n\n // @formatter:off\n @Nested\n // tag::default_timezone_class_level[]\n @DefaultTimeZone(\"CET\")\n // end::default_timezone_class_level[]\n inner\n // tag::default_timezone_class_level[]\n class MyTimeZoneTests {\n // end::default_timezone_class_level[]\n // @formatter:on\n // tag::default_timezone_class_level[]\n\n @Test\n fun test_with_class_level_configuration() {\n assertThat(TimeZone.getDefault()).isEqualTo(TimeZone.getTimeZone(\"CET\"))\n }\n\n @Test\n @DefaultTimeZone(\"Africa/Juba\")\n fun test_with_method_level_configuration() {\n assertThat(TimeZone.getDefault()).isEqualTo(TimeZone.getTimeZone(\"Africa/Juba\"))\n }\n }\n // end::default_timezone_class_level[]\n\n // tag::default_time_zone_with_provider[]\n @Test\n @DefaultTimeZone(timeZoneProvider = UtcTimeZoneProvider::class)\n fun test_with_time_zone_provider() {\n assertThat(TimeZone.getDefault()).isEqualTo(TimeZone.getTimeZone(\"UTC\"))\n }\n\n class UtcTimeZoneProvider : TimeZoneProvider {\n override fun get(): TimeZone = TimeZone.getTimeZone(ZoneOffset.UTC)\n }\n // end::default_time_zone_with_provider[]\n}\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/DisplayNameDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin\n\n// tag::user_guide[]\nimport org.junit.jupiter.api.DisplayName\nimport org.junit.jupiter.api.Test\n\n@DisplayName(\"A special test case\")\nclass DisplayNameDemo {\n @Test\n @DisplayName(\"Custom test name containing spaces\")\n fun testWithDisplayNameContainingSpaces() {\n }\n\n @Test\n @DisplayName(\"╯°□°）╯\")\n fun testWithDisplayNameContainingSpecialCharacters() {\n }\n\n @Test\n @DisplayName(\"😱\")\n fun testWithDisplayNameContainingEmoji() {\n }\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/DisplayNameGeneratorDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin\n\nimport org.junit.jupiter.api.DisplayName\nimport org.junit.jupiter.api.DisplayNameGeneration\nimport org.junit.jupiter.api.DisplayNameGenerator\nimport org.junit.jupiter.api.DisplayNameGenerator.IndicativeSentences.SentenceFragment\nimport org.junit.jupiter.api.DisplayNameGenerator.ReplaceUnderscores\nimport org.junit.jupiter.api.IndicativeSentencesGeneration\nimport org.junit.jupiter.api.Nested\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.params.ParameterizedTest\nimport org.junit.jupiter.params.provider.ValueSource\n\n@Suppress(\"ClassName\")\nclass DisplayNameGeneratorDemo {\n // @formatter:off\n @Nested\n // tag::user_guide_replace_underscores[]\n @DisplayNameGeneration(DisplayNameGenerator.ReplaceUnderscores::class)\n // end::user_guide_replace_underscores[]\n inner\n // tag::user_guide_replace_underscores[]\n class A_year_is_not_supported {\n // end::user_guide_replace_underscores[]\n // @formatter:on\n // tag::user_guide_replace_underscores[]\n @Test\n fun if_it_is_zero() {\n }\n\n @DisplayName(\"A negative value for year is not supported by the leap year computation.\")\n @ParameterizedTest(name = \"For example, year {0} is not supported.\")\n @ValueSource(ints = [-1, -4])\n fun if_it_is_negative(year: Int) {\n }\n }\n // end::user_guide_replace_underscores[]\n\n // @formatter:off\n @Nested\n // tag::user_guide_indicative_sentences[]\n @IndicativeSentencesGeneration(separator = \" -> \", generator = ReplaceUnderscores::class)\n // end::user_guide_indicative_sentences[]\n inner\n // tag::user_guide_indicative_sentences[]\n class A_year_is_a_leap_year {\n // end::user_guide_indicative_sentences[]\n // @formatter:on\n // tag::user_guide_indicative_sentences[]\n @Test\n fun if_it_is_divisible_by_4_but_not_by_100() {\n }\n\n @ParameterizedTest(name = \"Year {0} is a leap year.\")\n @ValueSource(ints = [2016, 2020, 2048])\n fun if_it_is_one_of_the_following_years(year: Int) {\n }\n }\n // end::user_guide_indicative_sentences[]\n\n // @formatter:off\n @Nested\n // tag::user_guide_custom_sentence_fragments[]\n @SentenceFragment(\"A year is a leap year\")\n @IndicativeSentencesGeneration\n // end::user_guide_custom_sentence_fragments[]\n inner\n // tag::user_guide_custom_sentence_fragments[]\n class LeapYearTests {\n // end::user_guide_custom_sentence_fragments[]\n // @formatter:on\n // tag::user_guide_custom_sentence_fragments[]\n @SentenceFragment(\"if it is divisible by 4 but not by 100\")\n @Test\n fun divisibleBy4ButNotBy100() {\n }\n\n @SentenceFragment(\"if it is one of the following years\")\n @ParameterizedTest(name = \"{0}\")\n @ValueSource(ints = [2016, 2020, 2048])\n fun validLeapYear(year: Int) {\n }\n }\n // end::user_guide_custom_sentence_fragments[]\n}\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/DynamicTestsDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin\n\n// tag::user_guide[]\nimport example.util.Calculator\nimport example.util.StringUtils.isPalindrome\nimport org.junit.jupiter.api.Assertions.assertEquals\nimport org.junit.jupiter.api.Assertions.assertFalse\nimport org.junit.jupiter.api.Assertions.assertNotNull\nimport org.junit.jupiter.api.Assertions.assertTrue\nimport org.junit.jupiter.api.DynamicContainer.dynamicContainer\nimport org.junit.jupiter.api.DynamicNode\nimport org.junit.jupiter.api.DynamicTest\nimport org.junit.jupiter.api.DynamicTest.dynamicTest\nimport org.junit.jupiter.api.Tag\nimport org.junit.jupiter.api.TestFactory\nimport org.junit.jupiter.api.parallel.Execution\nimport org.junit.jupiter.api.parallel.ExecutionMode.CONCURRENT\nimport org.junit.jupiter.api.parallel.ExecutionMode.SAME_THREAD\nimport java.util.Random\nimport java.util.stream.IntStream\nimport java.util.stream.Stream\n\n// end::user_guide[]\n// tag::user_guide[]\nclass DynamicTestsDemo {\n private val calculator = Calculator()\n\n // This method will not be executed but produce a warning\n @TestFactory\n // end::user_guide[]\n @Tag(\"exclude\")\n fun dummy(): DynamicTest = dynamicTest(\"dummy\") {}\n\n // tag::user_guide[]\n fun dynamicTestsWithInvalidReturnType(): List = listOf(\"Hello\")\n\n @TestFactory\n fun dynamicTestsFromCollection(): Collection =\n listOf(\n dynamicTest(\"1st dynamic test\") { assertTrue(isPalindrome(\"madam\")) },\n dynamicTest(\"2nd dynamic test\") { assertEquals(4, calculator.multiply(2, 2)) }\n )\n\n @TestFactory\n fun dynamicTestsFromIterable(): Iterable =\n listOf(\n dynamicTest(\"3rd dynamic test\") { assertTrue(isPalindrome(\"madam\")) },\n dynamicTest(\"4th dynamic test\") { assertEquals(4, calculator.multiply(2, 2)) }\n )\n\n @TestFactory\n fun dynamicTestsFromIterator(): Iterator =\n listOf(\n dynamicTest(\"5th dynamic test\") { assertTrue(isPalindrome(\"madam\")) },\n dynamicTest(\"6th dynamic test\") { assertEquals(4, calculator.multiply(2, 2)) }\n ).iterator()\n\n @TestFactory\n fun dynamicTestsFromArray(): Array =\n arrayOf(\n dynamicTest(\"7th dynamic test\") { assertTrue(isPalindrome(\"madam\")) },\n dynamicTest(\"8th dynamic test\") { assertEquals(4, calculator.multiply(2, 2)) }\n )\n\n @TestFactory\n fun dynamicTestsFromStream(): Stream =\n Stream\n .of(\"racecar\", \"radar\", \"mom\", \"dad\")\n .map { text -> dynamicTest(text) { assertTrue(isPalindrome(text)) } }\n\n @TestFactory\n fun dynamicTestsFromSequence(): Sequence =\n sequenceOf(\"racecar\", \"radar\", \"mom\", \"dad\")\n .map { text -> dynamicTest(text) { assertTrue(isPalindrome(text)) } }\n\n @TestFactory\n fun dynamicTestsFromIntStream(): Stream {\n // Generates tests for the first 10 even integers.\n return IntStream\n .iterate(0) { n -> n + 2 }\n .limit(10)\n .mapToObj { n -> dynamicTest(\"test$n\") { assertEquals(0, n % 2) } }\n }\n\n @TestFactory\n fun generateRandomNumberOfTests(): Stream {\n // Generates random positive integers between 0 and 100 until\n // a number evenly divisible by 7 is encountered.\n val inputGenerator =\n object : Iterator {\n var random = Random()\n\n // end::user_guide[]\n init {\n // Use fixed seed to always produce the same number of tests for execution on the CI server\n random = Random(23)\n }\n\n // tag::user_guide[]\n var current = 0\n\n override fun hasNext(): Boolean {\n current = random.nextInt(100)\n return current % 7 != 0\n }\n\n override fun next(): Int = current\n }\n\n // Generates display names like: input:5, input:37, input:85, etc.\n val displayNameGenerator = { input: Int -> \"input:$input\" }\n\n // Executes tests based on the current input value.\n val testExecutor = { input: Int -> assertTrue(input % 7 != 0) }\n\n // Returns a stream of dynamic tests.\n return DynamicTest.stream(inputGenerator, displayNameGenerator, testExecutor)\n }\n\n @TestFactory\n fun dynamicTestsFromStreamFactoryMethod(): Stream {\n // Stream of palindromes to check\n val inputStream = Stream.of(\"racecar\", \"radar\", \"mom\", \"dad\")\n\n // Generates display names like: racecar is a palindrome\n val displayNameGenerator = { text: String -> \"$text is a palindrome\" }\n\n // Executes tests based on the current input value.\n val testExecutor = { text: String -> assertTrue(isPalindrome(text)) }\n\n // Returns a stream of dynamic tests.\n return DynamicTest.stream(inputStream, displayNameGenerator, testExecutor)\n }\n\n @TestFactory\n fun dynamicTestsWithContainers(): Stream =\n Stream\n .of(\"A\", \"B\", \"C\")\n .map { input ->\n dynamicContainer(\n \"Container $input\",\n Stream.of(\n dynamicTest(\"not null\") { assertNotNull(input) },\n dynamicContainer(\n \"properties\",\n Stream.of(\n dynamicTest(\"length > 0\") { assertTrue(input.length > 0) },\n dynamicTest(\"not empty\") { assertFalse(input.isEmpty()) }\n )\n )\n )\n )\n }\n\n // end::user_guide[]\n // tag::execution_mode[]\n @TestFactory\n @Execution(CONCURRENT) // <1>\n fun dynamicTestsWithConfiguredExecutionMode(): Stream =\n Stream\n .of(\"A\", \"B\", \"C\")\n .map { input ->\n dynamicContainer { outer ->\n outer\n .displayName(\"Container $input\")\n .children(\n dynamicTest { config ->\n config\n .displayName(\"not null\")\n .executionMode(SAME_THREAD) // <2>\n .executable { assertNotNull(input) }\n },\n dynamicContainer { inner ->\n inner\n .displayName(\"properties\")\n .executionMode(CONCURRENT) // <3>\n .childExecutionMode(SAME_THREAD) // <4>\n .children(\n dynamicTest { config ->\n config\n .displayName(\"length > 0\")\n .executionMode(CONCURRENT) // <5>\n .executable { assertTrue(input.length > 0) }\n },\n dynamicTest { config ->\n config\n .displayName(\"not empty\")\n .executable { assertFalse(input.isEmpty()) }\n }\n )\n }\n )\n }\n }\n // end::execution_mode[]\n\n // tag::user_guide[]\n @TestFactory\n fun dynamicNodeSingleTest(): DynamicNode = dynamicTest(\"'pop' is a palindrome\") { assertTrue(isPalindrome(\"pop\")) }\n\n @TestFactory\n fun dynamicNodeSingleContainer(): DynamicNode =\n dynamicContainer(\n \"palindromes\",\n Stream\n .of(\"racecar\", \"radar\", \"mom\", \"dad\")\n .map { text -> dynamicTest(text) { assertTrue(isPalindrome(text)) } }\n )\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/DynamicTestsNamedDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin\n\n// tag::user_guide[]\n\nimport example.util.StringUtils.isPalindrome\nimport org.junit.jupiter.api.Assertions.assertTrue\nimport org.junit.jupiter.api.DynamicTest\nimport org.junit.jupiter.api.Named.named\nimport org.junit.jupiter.api.NamedExecutable\nimport org.junit.jupiter.api.TestFactory\nimport java.util.stream.Stream\n\nclass DynamicTestsNamedDemo {\n @TestFactory\n fun dynamicTestsFromStreamFactoryMethodWithNames(): Stream {\n // Stream of palindromes to check\n // end::user_guide[]\n // tag::user_guide[]\n val inputStream =\n Stream.of(\n named(\"racecar is a palindrome\", \"racecar\"),\n named(\"radar is also a palindrome\", \"radar\"),\n named(\"mom also seems to be a palindrome\", \"mom\"),\n named(\"dad is yet another palindrome\", \"dad\")\n )\n // end::user_guide[]\n // tag::user_guide[]\n\n // Returns a stream of dynamic tests.\n return DynamicTest.stream(inputStream) { text -> assertTrue(isPalindrome(text)) }\n }\n\n @TestFactory\n fun dynamicTestsFromStreamFactoryMethodWithNamedExecutables(): Stream {\n // Stream of palindromes to check\n // end::user_guide[]\n // tag::user_guide[]\n val inputStream =\n Stream\n .of(\"racecar\", \"radar\", \"mom\", \"dad\")\n .map { PalindromeNamedExecutable(it) }\n // end::user_guide[]\n // tag::user_guide[]\n\n // Returns a stream of dynamic tests based on NamedExecutables.\n return DynamicTest.stream(inputStream)\n }\n\n class PalindromeNamedExecutable(\n private val text: String\n ) : NamedExecutable {\n override fun getName(): String = \"'$text' is a palindrome\"\n\n override fun execute() {\n assertTrue(isPalindrome(text))\n }\n }\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/ExternalCustomConditionDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin\n\n// tag::user_guide_external_custom_condition[]\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.condition.EnabledIf\n\nclass ExternalCustomConditionDemo {\n @Test\n @EnabledIf(\"example.kotlin.ExternalCondition#customCondition\")\n fun enabled() {\n // ...\n }\n}\n\nclass ExternalCondition {\n companion object {\n @JvmStatic\n fun customCondition(): Boolean = true\n }\n}\n// end::user_guide_external_custom_condition[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/Fast.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin\n\n// tag::user_guide[]\nimport org.junit.jupiter.api.Tag\n\n@Target(AnnotationTarget.TYPE, AnnotationTarget.FUNCTION)\n@Retention(AnnotationRetention.RUNTIME)\n@Tag(\"fast\")\nannotation class Fast\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/FastTest.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin\n\n// tag::user_guide[]\nimport org.junit.jupiter.api.Tag\nimport org.junit.jupiter.api.Test\n\n@Target(AnnotationTarget.FUNCTION)\n@Retention(AnnotationRetention.RUNTIME)\n@Tag(\"fast\")\n@Test\nannotation class FastTest\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/HttpServerDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin\n\nimport com.sun.net.httpserver.HttpServer\nimport example.kotlin.extensions.HttpServerExtension\nimport org.junit.jupiter.api.Assertions.assertEquals\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.extension.ExtendWith\nimport java.net.HttpURLConnection\nimport java.net.URI\nimport java.net.URL\n\n// tag::user_guide[]\n@ExtendWith(HttpServerExtension::class)\nclass HttpServerDemo {\n // end::user_guide[]\n @Suppress(\"HttpUrlsUsage\")\n // tag::user_guide[]\n @Test\n fun httpCall(server: HttpServer) {\n val address = server.address\n val requestUrl = URI(\"http://${address.hostName}:${address.port}/example\").toURL()\n\n val responseBody = sendRequest(requestUrl)\n\n assertEquals(\"This is a test\", responseBody)\n }\n\n private fun sendRequest(url: URL): String {\n val connection = url.openConnection() as HttpURLConnection\n val contentLength = connection.contentLength\n url.openStream().use { response ->\n val content = ByteArray(contentLength)\n assertEquals(contentLength, response.read(content))\n return String(content, Charsets.UTF_8)\n }\n }\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/MyFirstJUnitJupiterTests.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin\n\n// tag::user_guide[]\n\nimport example.util.Calculator\nimport org.junit.jupiter.api.Assertions.assertEquals\nimport org.junit.jupiter.api.Test\n\nclass MyFirstJUnitJupiterTests {\n private val calculator = Calculator()\n\n @Test\n fun addition() {\n assertEquals(2, calculator.add(1, 1))\n }\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/MyRandomParametersTest.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin\n\nimport example.extensions.Random\nimport org.junit.jupiter.api.Assertions.assertNotEquals\nimport org.junit.jupiter.api.Test\n\n// tag::user_guide[]\nclass MyRandomParametersTest(\n @Random randomNumber: Int\n) {\n @Test\n fun injectsInteger(\n @Random i: Int,\n @Random j: Int\n ) {\n assertNotEquals(i, j)\n }\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/ParameterizedClassDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin\n\nimport org.junit.jupiter.api.Assertions.assertFalse\nimport org.junit.jupiter.api.Assertions.assertTrue\nimport org.junit.jupiter.api.Nested\nimport org.junit.jupiter.api.parallel.Execution\nimport org.junit.jupiter.api.parallel.ExecutionMode.SAME_THREAD\nimport org.junit.jupiter.params.Parameter\nimport org.junit.jupiter.params.ParameterizedClass\nimport org.junit.jupiter.params.ParameterizedTest\nimport org.junit.jupiter.params.provider.ValueSource\nimport java.time.Duration\n\nclass ParameterizedClassDemo {\n // @formatter:off\n @Nested\n // tag::nested[]\n @Execution(SAME_THREAD)\n @ParameterizedClass\n @ValueSource(strings = [\"apple\", \"banana\"])\n // end::nested[]\n inner\n // tag::nested[]\n class FruitTests {\n // end::nested[]\n // @formatter:on\n // tag::nested[]\n @Parameter\n lateinit var fruit: String\n\n @Nested\n @ParameterizedClass\n @ValueSource(ints = [23, 42])\n inner class QuantityTests {\n @Parameter\n var quantity: Int = 0\n\n @ParameterizedTest\n @ValueSource(strings = [\"PT1H\", \"PT2H\"])\n fun test(duration: Duration) {\n assertFruit(fruit)\n assertQuantity(quantity)\n assertFalse(duration.isNegative)\n }\n }\n }\n // end::nested[]\n\n private fun assertFruit(fruit: String) {\n assertTrue(\n listOf(\"apple\", \"banana\", \"cherry\", \"dewberry\").contains(fruit)\n ) { \"not a fruit: $fruit\" }\n }\n\n private fun assertQuantity(quantity: Int) {\n assertTrue(quantity > 0)\n }\n}\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/PollingTimeoutDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin\n\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.Timeout\n\nclass PollingTimeoutDemo {\n // tag::user_guide[]\n @Test\n @Timeout(5) // Poll at most 5 seconds\n fun pollUntil() {\n while (asynchronousResultNotAvailable()) {\n Thread.sleep(250) // custom poll interval\n }\n // Obtain the asynchronous result and perform assertions\n }\n // end::user_guide[]\n\n private fun asynchronousResultNotAvailable(): Boolean = false\n}\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/RepeatedTestsDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin\n\n// tag::user_guide[]\nimport org.junit.jupiter.api.Assertions.assertEquals\nimport org.junit.jupiter.api.BeforeEach\nimport org.junit.jupiter.api.DisplayName\nimport org.junit.jupiter.api.RepeatedTest\nimport org.junit.jupiter.api.RepetitionInfo\nimport org.junit.jupiter.api.TestInfo\nimport org.junit.jupiter.api.fail\nimport org.junit.jupiter.api.parallel.Execution\nimport org.junit.jupiter.api.parallel.ExecutionMode.SAME_THREAD\nimport java.util.logging.Logger\n\n@Execution(SAME_THREAD)\nclass RepeatedTestsDemo {\n private val logger = // ...\n // end::user_guide[]\n Logger.getLogger(RepeatedTestsDemo::class.java.name)\n // tag::user_guide[]\n\n @BeforeEach\n fun beforeEach(\n testInfo: TestInfo,\n repetitionInfo: RepetitionInfo\n ) {\n val currentRepetition = repetitionInfo.currentRepetition\n val totalRepetitions = repetitionInfo.totalRepetitions\n val methodName = testInfo.testMethod.get().name\n logger.info(\"About to execute repetition $currentRepetition of $totalRepetitions for $methodName\")\n }\n\n @RepeatedTest(10)\n fun repeatedTest() {\n // ...\n }\n\n @RepeatedTest(5)\n fun repeatedTestWithRepetitionInfo(repetitionInfo: RepetitionInfo) {\n assertEquals(5, repetitionInfo.totalRepetitions)\n }\n\n // end::user_guide[]\n // Use fully qualified name to avoid having it show up in the imports.\n @org.junit.jupiter.api.Disabled(\"intentional failures would break the build\")\n // tag::user_guide[]\n @RepeatedTest(value = 8, failureThreshold = 2)\n fun repeatedTestWithFailureThreshold(repetitionInfo: RepetitionInfo) {\n // Simulate unexpected failure every second repetition\n if (repetitionInfo.currentRepetition % 2 == 0) {\n fail(\"Boom!\")\n }\n }\n\n @RepeatedTest(value = 1, name = \"{displayName} {currentRepetition}/{totalRepetitions}\")\n @DisplayName(\"Repeat!\")\n fun customDisplayName(testInfo: TestInfo) {\n assertEquals(\"Repeat! 1/1\", testInfo.displayName)\n }\n\n @RepeatedTest(value = 1, name = RepeatedTest.LONG_DISPLAY_NAME)\n @DisplayName(\"Details...\")\n fun customDisplayNameWithLongPattern(testInfo: TestInfo) {\n assertEquals(\"Details... :: repetition 1 of 1\", testInfo.displayName)\n }\n\n @RepeatedTest(value = 5, name = \"Wiederholung {currentRepetition} von {totalRepetitions}\")\n fun repeatedTestInGerman() {\n // ...\n }\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/StandardTests.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin\n\n// tag::user_guide[]\nimport org.junit.jupiter.api.AfterAll\nimport org.junit.jupiter.api.AfterEach\nimport org.junit.jupiter.api.Assumptions.assumeTrue\nimport org.junit.jupiter.api.BeforeAll\nimport org.junit.jupiter.api.BeforeEach\nimport org.junit.jupiter.api.Disabled\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.fail\n\nclass StandardTests {\n @BeforeEach\n fun init() {\n }\n\n @Test\n fun succeedingTest() {\n }\n\n // end::user_guide[]\n @extensions.ExpectToFail\n // tag::user_guide[]\n @Test\n fun failingTest() {\n fail(\"a failing test\")\n }\n\n @Test\n @Disabled(\"for demonstration purposes\")\n fun skippedTest() {\n // not executed\n }\n\n @Test\n fun abortedTest() {\n assumeTrue(\"abc\".contains(\"Z\"))\n fail(\"test should have been aborted\")\n }\n\n @AfterEach\n fun tearDown() {\n }\n\n companion object {\n @JvmStatic\n @BeforeAll\n fun initAll() {\n }\n\n @JvmStatic\n @AfterAll\n fun tearDownAll() {\n }\n }\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/SystemPropertyExtensionDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin\n\nimport org.assertj.core.api.Assertions.assertThat\nimport org.junit.jupiter.api.BeforeAll\nimport org.junit.jupiter.api.BeforeEach\nimport org.junit.jupiter.api.ClassOrderer\nimport org.junit.jupiter.api.Nested\nimport org.junit.jupiter.api.Order\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.TestClassOrder\nimport org.junit.jupiter.api.TestInstance\nimport org.junit.jupiter.api.util.ClearSystemProperty\nimport org.junit.jupiter.api.util.ReadsSystemProperty\nimport org.junit.jupiter.api.util.RestoreSystemProperties\nimport org.junit.jupiter.api.util.SetSystemProperty\nimport org.junit.jupiter.params.ParameterizedTest\nimport org.junit.jupiter.params.provider.ValueSource\n\nclass SystemPropertyExtensionDemo {\n // tag::systemproperty_clear_simple[]\n @Test\n @ClearSystemProperty(key = \"some property\")\n fun testClearingProperty() {\n assertThat(System.getProperty(\"some property\")).isNull()\n }\n // end::systemproperty_clear_simple[]\n\n // tag::systemproperty_set_simple[]\n @Test\n @SetSystemProperty(key = \"some property\", value = \"new value\")\n fun testSettingProperty() {\n assertThat(System.getProperty(\"some property\")).isEqualTo(\"new value\")\n }\n // end::systemproperty_set_simple[]\n\n // tag::systemproperty_using_set_and_clear[]\n @Test\n @ClearSystemProperty(key = \"1st property\")\n @ClearSystemProperty(key = \"2nd property\")\n @SetSystemProperty(key = \"3rd property\", value = \"new value\")\n fun testClearingAndSettingProperty() {\n assertThat(System.getProperty(\"1st property\")).isNull()\n assertThat(System.getProperty(\"2nd property\")).isNull()\n assertThat(System.getProperty(\"3rd property\")).isEqualTo(\"new value\")\n }\n // end::systemproperty_using_set_and_clear[]\n\n // @formatter:off\n @Nested\n // tag::systemproperty_using_at_class_level[]\n @ClearSystemProperty(key = \"some property\")\n // end::systemproperty_using_at_class_level[]\n inner\n // tag::systemproperty_using_at_class_level[]\n class MySystemPropertyTest {\n // end::systemproperty_using_at_class_level[]\n // @formatter:on\n // tag::systemproperty_using_at_class_level[]\n\n @Test\n @SetSystemProperty(key = \"some property\", value = \"new value\")\n fun clearedAtClasslevel() {\n assertThat(System.getProperty(\"some property\")).isEqualTo(\"new value\")\n }\n }\n // end::systemproperty_using_at_class_level[]\n\n // tag::systemproperty_restore_test[]\n @ParameterizedTest\n @ValueSource(strings = [\"foo\", \"bar\"])\n @RestoreSystemProperties\n fun parameterizedTest(value: String) {\n System.setProperty(\"some parameterized property\", value)\n System.setProperty(\"some other dynamic property\", \"my code calculates somehow\")\n }\n // end::systemproperty_restore_test[]\n\n @Nested\n @TestClassOrder(ClassOrderer.OrderAnnotation::class)\n inner class SystemPropertyRestoreExample {\n // @formatter:off\n @Nested\n @Order(1)\n // tag::systemproperty_class_restore_setup[]\n @TestInstance(TestInstance.Lifecycle.PER_CLASS)\n @RestoreSystemProperties\n // end::systemproperty_class_restore_setup[]\n inner\n // tag::systemproperty_class_restore_setup[]\n class MySystemPropertyRestoreTest {\n // end::systemproperty_class_restore_setup[]\n // @formatter:on\n // tag::systemproperty_class_restore_setup[]\n @BeforeAll\n fun beforeAll() {\n System.setProperty(\"A\", \"A value\")\n }\n\n @BeforeEach\n fun beforeEach() {\n System.setProperty(\"B\", \"B value\")\n }\n\n @Test\n fun isolatedTest1() {\n System.setProperty(\"C\", \"C value\")\n }\n\n @Test\n fun isolatedTest2() {\n assertThat(System.getProperty(\"A\")).isEqualTo(\"A value\")\n assertThat(System.getProperty(\"B\")).isEqualTo(\"B value\")\n\n // Class-level @RestoreSystemProperties restores \"C\" to original state\n assertThat(System.getProperty(\"C\")).isNull()\n }\n }\n // end::systemproperty_class_restore_setup[]\n\n // @formatter:off\n @Nested\n @Order(2)\n // tag::systemproperty_class_restore_isolated_class[]\n @ReadsSystemProperty\n // end::systemproperty_class_restore_isolated_class[]\n inner\n // tag::systemproperty_class_restore_isolated_class[]\n class SomeOtherTestClass {\n // end::systemproperty_class_restore_isolated_class[]\n // @formatter:on\n // tag::systemproperty_class_restore_isolated_class[]\n @Test\n fun isolatedTest() {\n assertThat(System.getProperty(\"A\")).isNull()\n assertThat(System.getProperty(\"B\")).isNull()\n assertThat(System.getProperty(\"C\")).isNull()\n }\n }\n // end::systemproperty_class_restore_isolated_class[]\n }\n\n // tag::systemproperty_method_combine_all_test[]\n @ParameterizedTest\n @ValueSource(ints = [100, 500, 1000])\n @RestoreSystemProperties\n @SetSystemProperty(key = \"DISABLE_CACHE\", value = \"TRUE\")\n @ClearSystemProperty(key = \"COPYWRITE_OVERLAY_TEXT\")\n fun imageGenerationTest(imageSize: Int) {\n System.setProperty(\"IMAGE_SIZE\", \"$imageSize\") // Requires restore\n\n // Test your image generation utility with the current system properties\n }\n // end::systemproperty_method_combine_all_test[]\n}\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/TempDirectoryDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin\n\nimport com.google.common.jimfs.Configuration\nimport com.google.common.jimfs.Jimfs\nimport example.kotlin.TempDirectoryDemo.InMemoryTempDirDemo.JimfsTempDirFactory\nimport example.util.ListWriter\nimport org.junit.jupiter.api.Assertions.assertEquals\nimport org.junit.jupiter.api.Assertions.assertNotEquals\nimport org.junit.jupiter.api.Assertions.assertTrue\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.extension.AnnotatedElementContext\nimport org.junit.jupiter.api.extension.ExtensionContext\nimport org.junit.jupiter.api.io.CleanupMode.ON_SUCCESS\nimport org.junit.jupiter.api.io.TempDir\nimport org.junit.jupiter.api.io.TempDirDeletionStrategy\nimport org.junit.jupiter.api.io.TempDirFactory\nimport java.nio.file.FileSystem\nimport java.nio.file.Files\nimport java.nio.file.Path\n\n@Suppress(\"ClassName\")\nclass TempDirectoryDemo {\n // tag::user_guide_parameter_injection[]\n @Test\n fun writeItemsToFile(\n @TempDir tempDir: Path\n ) {\n val file = tempDir.resolve(\"test.txt\")\n\n ListWriter(file).write(\"a\", \"b\", \"c\")\n\n assertEquals(listOf(\"a,b,c\"), Files.readAllLines(file))\n }\n // end::user_guide_parameter_injection[]\n\n // tag::user_guide_multiple_directories[]\n @Test\n fun copyFileFromSourceToTarget(\n @TempDir source: Path,\n @TempDir target: Path\n ) {\n val sourceFile = source.resolve(\"test.txt\")\n ListWriter(sourceFile).write(\"a\", \"b\", \"c\")\n\n val targetFile = Files.copy(sourceFile, target.resolve(\"test.txt\"))\n\n assertNotEquals(sourceFile, targetFile)\n assertEquals(listOf(\"a,b,c\"), Files.readAllLines(targetFile))\n }\n // end::user_guide_multiple_directories[]\n\n // tag::user_guide_field_injection[]\n class SharedTempDirectoryDemo {\n @Test\n fun writeItemsToFile() {\n val file = sharedTempDir.resolve(\"test.txt\")\n\n ListWriter(file).write(\"a\", \"b\", \"c\")\n\n assertEquals(listOf(\"a,b,c\"), Files.readAllLines(file))\n }\n\n @Test\n fun anotherTestThatUsesTheSameTempDir() {\n // use sharedTempDir\n }\n\n companion object {\n @TempDir\n @JvmStatic\n lateinit var sharedTempDir: Path\n }\n }\n // end::user_guide_field_injection[]\n\n // tag::user_guide_cleanup_mode[]\n class CleanupModeDemo {\n @Test\n fun fileTest(\n @TempDir(cleanup = ON_SUCCESS) tempDir: Path\n ) {\n // perform test\n }\n }\n // end::user_guide_cleanup_mode[]\n\n // tag::user_guide_factory_name_prefix[]\n class TempDirFactoryDemo {\n @Test\n fun factoryTest(\n @TempDir(factory = Factory::class) tempDir: Path\n ) {\n assertTrue(tempDir.fileName.toString().startsWith(\"factoryTest\"))\n }\n\n class Factory : TempDirFactory {\n override fun createTempDirectory(\n elementContext: AnnotatedElementContext,\n extensionContext: ExtensionContext\n ): Path = Files.createTempDirectory(extensionContext.requiredTestMethod.name)\n }\n }\n // end::user_guide_factory_name_prefix[]\n\n // tag::user_guide_factory_jimfs[]\n class InMemoryTempDirDemo {\n @Test\n fun test(\n @TempDir(factory = JimfsTempDirFactory::class) tempDir: Path\n ) {\n // perform test\n }\n\n class JimfsTempDirFactory : TempDirFactory {\n private val fileSystem: FileSystem = Jimfs.newFileSystem(Configuration.unix())\n\n override fun createTempDirectory(\n elementContext: AnnotatedElementContext,\n extensionContext: ExtensionContext\n ): Path = Files.createTempDirectory(fileSystem.getPath(\"/\"), \"junit-\")\n\n override fun close() {\n fileSystem.close()\n }\n }\n }\n // end::user_guide_factory_jimfs[]\n\n // tag::user_guide_deletion_strategy[]\n class DeletionStrategyDemo {\n @Test\n fun test(\n @TempDir(deletionStrategy = TempDirDeletionStrategy.IgnoreFailures::class)\n tempDir: Path\n ) {\n // perform test\n }\n }\n // end::user_guide_deletion_strategy[]\n\n // tag::user_guide_composed_annotation[]\n @Target(AnnotationTarget.ANNOTATION_CLASS, AnnotationTarget.FIELD, AnnotationTarget.VALUE_PARAMETER)\n @Retention(AnnotationRetention.RUNTIME)\n @TempDir(factory = JimfsTempDirFactory::class)\n annotation class JimfsTempDir\n // end::user_guide_composed_annotation[]\n\n // tag::user_guide_composed_annotation_usage[]\n class JimfsTempDirAnnotationDemo {\n @Test\n fun test(\n @JimfsTempDir tempDir: Path\n ) {\n // perform test\n }\n }\n // end::user_guide_composed_annotation_usage[]\n}\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/TestInfoDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin\n\n// tag::user_guide[]\n\nimport org.junit.jupiter.api.Assertions.assertEquals\nimport org.junit.jupiter.api.Assertions.assertTrue\nimport org.junit.jupiter.api.BeforeAll\nimport org.junit.jupiter.api.BeforeEach\nimport org.junit.jupiter.api.DisplayName\nimport org.junit.jupiter.api.Tag\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.TestInfo\n\n@DisplayName(\"TestInfo Demo\")\nclass TestInfoDemo(\n testInfo: TestInfo\n) {\n companion object {\n @JvmStatic\n @BeforeAll\n fun beforeAll(testInfo: TestInfo) {\n assertEquals(\"TestInfo Demo\", testInfo.displayName)\n }\n }\n\n init {\n assertTrue(testInfo.displayName in listOf(\"TEST 1\", \"test2()\"))\n }\n\n @BeforeEach\n fun init(testInfo: TestInfo) {\n assertTrue(testInfo.displayName in listOf(\"TEST 1\", \"test2()\"))\n }\n\n @Test\n @DisplayName(\"TEST 1\")\n @Tag(\"my-tag\")\n fun test1(testInfo: TestInfo) {\n assertEquals(\"TEST 1\", testInfo.displayName)\n assertTrue(\"my-tag\" in testInfo.tags)\n }\n\n @Test\n fun test2() {\n }\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/TestReporterDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin\n\nimport org.junit.jupiter.api.MediaType\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.TestReporter\nimport org.junit.jupiter.api.io.TempDir\nimport java.nio.file.Files\nimport java.nio.file.Path\n\n// tag::user_guide[]\nclass TestReporterDemo {\n @Test\n fun reportSingleValue(testReporter: TestReporter) {\n testReporter.publishEntry(\"a status message\")\n }\n\n @Test\n fun reportKeyValuePair(testReporter: TestReporter) {\n testReporter.publishEntry(\"a key\", \"a value\")\n }\n\n @Test\n fun reportMultipleKeyValuePairs(testReporter: TestReporter) {\n testReporter.publishEntry(\n mapOf(\n \"user name\" to \"dk38\",\n \"award year\" to \"1974\"\n )\n )\n }\n\n @Test\n fun reportFiles(\n testReporter: TestReporter,\n @TempDir tempDir: Path\n ) {\n testReporter.publishFile(\"test1.txt\", MediaType.TEXT_PLAIN_UTF_8) { file ->\n Files.write(file, listOf(\"Test 1\"))\n }\n\n val existingFile = Files.write(tempDir.resolve(\"test2.txt\"), listOf(\"Test 2\"))\n testReporter.publishFile(existingFile, MediaType.TEXT_PLAIN_UTF_8)\n\n testReporter.publishDirectory(\"test3\") { dir ->\n Files.write(dir.resolve(\"nested1.txt\"), listOf(\"Nested content 1\"))\n Files.write(dir.resolve(\"nested2.txt\"), listOf(\"Nested content 2\"))\n }\n\n val existingDir = Files.createDirectory(tempDir.resolve(\"test4\"))\n Files.write(existingDir.resolve(\"nested1.txt\"), listOf(\"Nested content 1\"))\n Files.write(existingDir.resolve(\"nested2.txt\"), listOf(\"Nested content 2\"))\n testReporter.publishDirectory(existingDir)\n }\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/TestingAStackDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin\n\n// tag::user_guide[]\nimport org.junit.jupiter.api.Assertions.assertEquals\nimport org.junit.jupiter.api.Assertions.assertFalse\nimport org.junit.jupiter.api.Assertions.assertTrue\nimport org.junit.jupiter.api.BeforeEach\nimport org.junit.jupiter.api.DisplayName\nimport org.junit.jupiter.api.Nested\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.assertThrows\nimport java.util.EmptyStackException\nimport java.util.Stack\n\n@DisplayName(\"A stack\")\nclass TestingAStackDemo {\n @Test\n @DisplayName(\"is instantiated with new Stack()\")\n fun isInstantiatedWithNew() {\n Stack()\n }\n\n @Nested\n @DisplayName(\"when new\")\n inner class WhenNew {\n lateinit var stack: Stack\n\n @BeforeEach\n fun createNewStack() {\n stack = Stack()\n }\n\n @Test\n @DisplayName(\"is empty\")\n fun isEmpty() {\n assertTrue(stack.isEmpty())\n }\n\n @Test\n @DisplayName(\"throws EmptyStackException when popped\")\n fun throwsExceptionWhenPopped() {\n assertThrows { stack.pop() }\n }\n\n @Test\n @DisplayName(\"throws EmptyStackException when peeked\")\n fun throwsExceptionWhenPeeked() {\n assertThrows { stack.peek() }\n }\n\n @Nested\n @DisplayName(\"after pushing an element\")\n inner class AfterPushing {\n val anElement = \"an element\"\n\n @BeforeEach\n fun pushAnElement() {\n stack.push(anElement)\n }\n\n @Test\n @DisplayName(\"it is no longer empty\")\n fun isNotEmpty() {\n assertFalse(stack.isEmpty())\n }\n\n @Test\n @DisplayName(\"returns the element when popped and is empty\")\n fun returnElementWhenPopped() {\n assertEquals(anElement, stack.pop())\n assertTrue(stack.isEmpty())\n }\n\n @Test\n @DisplayName(\"returns the element when peeked but remains not empty\")\n fun returnElementWhenPeeked() {\n assertEquals(anElement, stack.peek())\n assertFalse(stack.isEmpty())\n }\n }\n }\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/TimeoutDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin\n\nimport org.junit.jupiter.api.BeforeEach\nimport org.junit.jupiter.api.Tag\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.Timeout\nimport org.junit.jupiter.api.Timeout.ThreadMode\nimport java.util.concurrent.TimeUnit\n\n// tag::user_guide[]\n@Tag(\"timeout\")\nclass TimeoutDemo {\n @BeforeEach\n @Timeout(5)\n fun setUp() {\n // fails if execution time exceeds 5 seconds\n }\n\n @Test\n @Timeout(value = 500, unit = TimeUnit.MILLISECONDS)\n fun failsIfExecutionTimeExceeds500Milliseconds() {\n // fails if execution time exceeds 500 milliseconds\n }\n\n @Test\n @Timeout(value = 500, unit = TimeUnit.MILLISECONDS, threadMode = ThreadMode.SEPARATE_THREAD)\n fun failsIfExecutionTimeExceeds500MillisecondsInSeparateThread() {\n // fails if execution time exceeds 500 milliseconds, the test code is executed in a separate thread\n }\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/defaultmethods/ComparableContract.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin.defaultmethods\n\nimport org.junit.jupiter.api.Assertions.assertEquals\nimport org.junit.jupiter.api.Assertions.assertTrue\nimport org.junit.jupiter.api.Test\n\n// tag::user_guide[]\ninterface ComparableContract> : Testable {\n fun createSmallerValue(): T\n\n @Test\n fun returnsZeroWhenComparedToItself() {\n val value = createValue()\n assertEquals(0, value.compareTo(value))\n }\n\n @Test\n fun returnsPositiveNumberWhenComparedToSmallerValue() {\n val value = createValue()\n val smallerValue = createSmallerValue()\n assertTrue(value > smallerValue)\n }\n\n @Test\n fun returnsNegativeNumberWhenComparedToLargerValue() {\n val value = createValue()\n val smallerValue = createSmallerValue()\n assertTrue(smallerValue < value)\n }\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/defaultmethods/EqualsContract.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin.defaultmethods\n\nimport org.junit.jupiter.api.Assertions.assertEquals\nimport org.junit.jupiter.api.Assertions.assertNotEquals\nimport org.junit.jupiter.api.Test\n\n// tag::user_guide[]\ninterface EqualsContract : Testable {\n fun createNotEqualValue(): T\n\n @Test\n fun valueEqualsItself() {\n val value = createValue()\n assertEquals(value, value)\n }\n\n @Test\n fun valueDoesNotEqualNull() {\n val value = createValue()\n assertNotEquals(null, value)\n }\n\n @Test\n fun valueDoesNotEqualDifferentValue() {\n val value = createValue()\n val differentValue = createNotEqualValue()\n assertNotEquals(value, differentValue)\n assertNotEquals(differentValue, value)\n }\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/defaultmethods/StringTests.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin.defaultmethods\n\n// tag::user_guide[]\nclass StringTests :\n ComparableContract,\n EqualsContract {\n override fun createValue() = \"banana\"\n\n override fun createSmallerValue() = \"apple\" // 'a' < 'b' in \"banana\"\n\n override fun createNotEqualValue() = \"cherry\"\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/defaultmethods/Testable.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin.defaultmethods\n\n// tag::user_guide[]\ninterface Testable {\n fun createValue(): T\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/exception/AssertDoesNotThrowExceptionDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin.exception\n\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.assertDoesNotThrow\n\nclass AssertDoesNotThrowExceptionDemo {\n // tag::user_guide[]\n @Test\n fun testExceptionIsNotThrown() {\n assertDoesNotThrow {\n shouldNotThrowException()\n }\n }\n\n fun shouldNotThrowException() {\n }\n // end::user_guide[]\n}\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/exception/ExceptionAssertionDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin.exception\n\nimport org.junit.jupiter.api.Assertions.assertEquals\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.assertThrows\n\nclass ExceptionAssertionDemo {\n // tag::user_guide[]\n @Test\n fun testExpectedExceptionIsThrown() {\n // The following assertion succeeds because the code under assertion\n // throws the expected IllegalArgumentException.\n // The assertion also returns the thrown exception which can be used for\n // further assertions like asserting the exception message.\n val exception =\n assertThrows {\n throw IllegalArgumentException(\"expected message\")\n }\n assertEquals(\"expected message\", exception.message)\n\n // The following assertion also succeeds because the code under assertion\n // throws IllegalArgumentException which is a subclass of RuntimeException.\n assertThrows {\n throw IllegalArgumentException(\"expected message\")\n }\n }\n // end::user_guide[]\n}\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/exception/ExceptionAssertionExactDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin.exception\n\nimport extensions.ExpectToFail\nimport org.junit.jupiter.api.Assertions.assertEquals\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.assertThrowsExactly\n\nclass ExceptionAssertionExactDemo {\n @ExpectToFail\n // tag::user_guide[]\n @Test\n fun testExpectedExceptionIsThrown() {\n // The following assertion succeeds because the code under assertion throws\n // IllegalArgumentException which is exactly equal to the expected type.\n // The assertion also returns the thrown exception which can be used for\n // further assertions like asserting the exception message.\n val exception =\n assertThrowsExactly {\n throw IllegalArgumentException(\"expected message\")\n }\n assertEquals(\"expected message\", exception.message)\n\n // The following assertion fails because the assertion expects exactly\n // RuntimeException to be thrown, not subclasses of RuntimeException.\n assertThrowsExactly {\n throw IllegalArgumentException(\"expected message\")\n }\n }\n // end::user_guide[]\n}\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/exception/FailedAssertionDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin.exception\n\nimport example.util.Calculator\nimport extensions.ExpectToFail\nimport org.junit.jupiter.api.Assertions.assertEquals\nimport org.junit.jupiter.api.Test\n\nclass FailedAssertionDemo {\n // tag::user_guide[]\n private val calculator = Calculator()\n\n // end::user_guide[]\n\n @ExpectToFail\n // tag::user_guide[]\n @Test\n fun failsDueToUncaughtAssertionError() {\n // The following incorrect assertion will cause a test failure.\n // The expected value should be 2 instead of 99.\n assertEquals(99, calculator.add(1, 1))\n }\n // end::user_guide[]\n}\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/exception/UncaughtExceptionHandlingDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin.exception\n\nimport example.util.Calculator\nimport extensions.ExpectToFail\nimport org.junit.jupiter.api.Test\n\nclass UncaughtExceptionHandlingDemo {\n // tag::user_guide[]\n private val calculator = Calculator()\n\n // end::user_guide[]\n\n @ExpectToFail\n // tag::user_guide[]\n @Test\n fun failsDueToUncaughtException() {\n // The following throws an ArithmeticException due to division by\n // zero, which causes a test failure.\n calculator.divide(1, 0)\n }\n // end::user_guide[]\n}\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/extensions/HttpServerExtension.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin.extensions\n\nimport com.sun.net.httpserver.HttpServer\nimport org.junit.jupiter.api.extension.ExtensionContext\nimport org.junit.jupiter.api.extension.ExtensionContext.Namespace\nimport org.junit.jupiter.api.extension.ParameterContext\nimport org.junit.jupiter.api.extension.ParameterResolver\nimport java.io.IOException\nimport java.io.UncheckedIOException\n\n// tag::user_guide[]\nclass HttpServerExtension : ParameterResolver {\n override fun supportsParameter(\n parameterContext: ParameterContext,\n extensionContext: ExtensionContext\n ): Boolean = HttpServer::class.java == parameterContext.parameter.type\n\n override fun resolveParameter(\n parameterContext: ParameterContext,\n extensionContext: ExtensionContext\n ): Any {\n val rootContext = extensionContext.root\n val store = rootContext.getStore(Namespace.GLOBAL)\n val key = HttpServerResource::class.java\n val resource =\n store.computeIfAbsent(key, {\n try {\n HttpServerResource(0).apply { start() }\n } catch (e: IOException) {\n throw UncheckedIOException(\"Failed to create HttpServerResource\", e)\n }\n }, HttpServerResource::class.java)\n return resource.httpServer\n }\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/extensions/HttpServerResource.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin.extensions\n\nimport com.sun.net.httpserver.HttpServer\nimport java.net.InetAddress\nimport java.net.InetSocketAddress\n\n// tag::user_guide[]\nclass HttpServerResource(\n port: Int\n) : AutoCloseable {\n val httpServer: HttpServer\n\n init {\n val loopbackAddress = InetAddress.getLoopbackAddress()\n httpServer = HttpServer.create(InetSocketAddress(loopbackAddress, port), 0)\n }\n\n // end::user_guide[]\n\n // tag::user_guide[]\n fun start() {\n // Example handler\n httpServer.createContext(\"/example\") { exchange ->\n val body = \"This is a test\"\n exchange.sendResponseHeaders(200, body.length.toLong())\n exchange.responseBody.use { os ->\n os.write(body.toByteArray(Charsets.UTF_8))\n }\n }\n httpServer.executor = null\n httpServer.start()\n }\n\n override fun close() {\n httpServer.stop(0)\n }\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/extensions/ParameterResolverConflictDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin.extensions\n\nimport org.junit.jupiter.api.Assertions.assertEquals\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.extension.ExtendWith\nimport org.junit.jupiter.api.extension.ExtensionContext\nimport org.junit.jupiter.api.extension.ParameterContext\nimport org.junit.jupiter.api.extension.ParameterResolver\n\n// tag::user_guide[]\nclass ParameterResolverConflictDemo {\n // end::user_guide[]\n @extensions.ExpectToFail\n // tag::user_guide[]\n @Test\n @ExtendWith(FirstIntegerResolver::class, SecondIntegerResolver::class)\n fun testInt(i: Int) {\n // Test will not run due to ParameterResolutionException\n assertEquals(1, i)\n }\n\n class FirstIntegerResolver : ParameterResolver {\n override fun supportsParameter(\n parameterContext: ParameterContext,\n extensionContext: ExtensionContext\n ): Boolean = parameterContext.parameter.type == Int::class.javaPrimitiveType\n\n override fun resolveParameter(\n parameterContext: ParameterContext,\n extensionContext: ExtensionContext\n ): Any = 1\n }\n\n class SecondIntegerResolver : ParameterResolver {\n override fun supportsParameter(\n parameterContext: ParameterContext,\n extensionContext: ExtensionContext\n ): Boolean = parameterContext.parameter.type == Int::class.javaPrimitiveType\n\n override fun resolveParameter(\n parameterContext: ParameterContext,\n extensionContext: ExtensionContext\n ): Any = 2\n }\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/extensions/ParameterResolverCustomAnnotationDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin.extensions\n\nimport org.junit.jupiter.api.Assertions.assertEquals\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.extension.ExtendWith\nimport org.junit.jupiter.api.extension.ExtensionContext\nimport org.junit.jupiter.api.extension.ParameterContext\nimport org.junit.jupiter.api.extension.ParameterResolver\n\n// tag::user_guide[]\nclass ParameterResolverCustomAnnotationDemo {\n @Test\n fun testInt(\n @FirstInteger first: Int,\n @SecondInteger second: Int\n ) {\n assertEquals(1, first)\n assertEquals(2, second)\n }\n\n @Target(AnnotationTarget.VALUE_PARAMETER)\n @Retention(AnnotationRetention.RUNTIME)\n @ExtendWith(FirstIntegerExtension::class)\n annotation class FirstInteger\n\n class FirstIntegerExtension : ParameterResolver {\n override fun supportsParameter(\n parameterContext: ParameterContext,\n extensionContext: ExtensionContext\n ): Boolean =\n parameterContext.parameter.type == Int::class.javaPrimitiveType &&\n !parameterContext.isAnnotated(SecondInteger::class.java)\n\n override fun resolveParameter(\n parameterContext: ParameterContext,\n extensionContext: ExtensionContext\n ): Any = 1\n }\n\n @Target(AnnotationTarget.VALUE_PARAMETER)\n @Retention(AnnotationRetention.RUNTIME)\n @ExtendWith(SecondIntegerExtension::class)\n annotation class SecondInteger\n\n class SecondIntegerExtension : ParameterResolver {\n override fun supportsParameter(\n parameterContext: ParameterContext,\n extensionContext: ExtensionContext\n ): Boolean = parameterContext.isAnnotated(SecondInteger::class.java)\n\n override fun resolveParameter(\n parameterContext: ParameterContext,\n extensionContext: ExtensionContext\n ): Any = 2\n }\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/extensions/ParameterResolverCustomTypeDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin.extensions\n\nimport org.junit.jupiter.api.Assertions.assertEquals\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.extension.ExtendWith\nimport org.junit.jupiter.api.extension.ExtensionContext\nimport org.junit.jupiter.api.extension.ParameterContext\nimport org.junit.jupiter.api.extension.ParameterResolver\n\n// tag::user_guide[]\nclass ParameterResolverCustomTypeDemo {\n @Test\n @ExtendWith(FirstIntegerResolver::class, SecondIntegerResolver::class)\n fun testInt(\n i: Int,\n wrappedInteger: WrappedInteger\n ) {\n assertEquals(1, i)\n assertEquals(2, wrappedInteger.value)\n }\n\n class FirstIntegerResolver : ParameterResolver {\n override fun supportsParameter(\n parameterContext: ParameterContext,\n extensionContext: ExtensionContext\n ): Boolean = parameterContext.parameter.type == Int::class.javaPrimitiveType\n\n override fun resolveParameter(\n parameterContext: ParameterContext,\n extensionContext: ExtensionContext\n ): Any = 1\n }\n\n class SecondIntegerResolver : ParameterResolver {\n override fun supportsParameter(\n parameterContext: ParameterContext,\n extensionContext: ExtensionContext\n ): Boolean = parameterContext.parameter.type == WrappedInteger::class.java\n\n override fun resolveParameter(\n parameterContext: ParameterContext,\n extensionContext: ExtensionContext\n ): Any = WrappedInteger(2)\n }\n\n data class WrappedInteger(\n val value: Int\n )\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/extensions/ParameterResolverNoConflictDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin.extensions\n\nimport org.junit.jupiter.api.Assertions.assertEquals\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.extension.ExtendWith\nimport org.junit.jupiter.api.extension.ExtensionContext\nimport org.junit.jupiter.api.extension.ParameterContext\nimport org.junit.jupiter.api.extension.ParameterResolver\n\n// tag::user_guide[]\nclass ParameterResolverNoConflictDemo {\n @Test\n @ExtendWith(FirstIntegerResolver::class)\n fun firstResolution(i: Int) {\n assertEquals(1, i)\n }\n\n @Test\n @ExtendWith(SecondIntegerResolver::class)\n fun secondResolution(i: Int) {\n assertEquals(2, i)\n }\n\n class FirstIntegerResolver : ParameterResolver {\n override fun supportsParameter(\n parameterContext: ParameterContext,\n extensionContext: ExtensionContext\n ): Boolean = parameterContext.parameter.type == Int::class.javaPrimitiveType\n\n override fun resolveParameter(\n parameterContext: ParameterContext,\n extensionContext: ExtensionContext\n ): Any = 1\n }\n\n class SecondIntegerResolver : ParameterResolver {\n override fun supportsParameter(\n parameterContext: ParameterContext,\n extensionContext: ExtensionContext\n ): Boolean = parameterContext.parameter.type == Int::class.javaPrimitiveType\n\n override fun resolveParameter(\n parameterContext: ParameterContext,\n extensionContext: ExtensionContext\n ): Any = 2\n }\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/extensions/Random.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin.extensions\n\nimport org.junit.jupiter.api.extension.ExtendWith\n\n// tag::user_guide[]\n@Target(AnnotationTarget.FIELD, AnnotationTarget.VALUE_PARAMETER)\n@Retention(AnnotationRetention.RUNTIME)\n@ExtendWith(RandomNumberExtension::class)\nannotation class Random\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/extensions/RandomNumberDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin.extensions\n\nimport org.junit.jupiter.api.BeforeEach\nimport org.junit.jupiter.api.Test\n\n// tag::user_guide[]\nclass RandomNumberDemo(\n @Random randomNumber2: Int\n) {\n // Use randomNumber1 field in test methods and @BeforeEach\n // or @AfterEach lifecycle methods.\n @Random\n var randomNumber1: Int = 0\n\n // randomNumber2 is available in the constructor via primary constructor above.\n\n @BeforeEach\n fun beforeEach(\n @Random randomNumber3: Int\n ) {\n // Use randomNumber3 in @BeforeEach method.\n }\n\n @Test\n fun test(\n @Random randomNumber4: Int\n ) {\n // Use randomNumber4 in test method.\n }\n\n companion object {\n // Use static randomNumber0 field anywhere in the test class,\n // including @BeforeAll or @AfterAll lifecycle methods.\n @Random\n @JvmStatic\n var randomNumber0: Int = 0\n }\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/extensions/RandomNumberExtension.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin.extensions\n\n// tag::user_guide[]\nimport org.junit.jupiter.api.extension.BeforeAllCallback\nimport org.junit.jupiter.api.extension.ExtensionContext\nimport org.junit.jupiter.api.extension.ParameterContext\nimport org.junit.jupiter.api.extension.ParameterResolver\nimport org.junit.jupiter.api.extension.TestInstancePostProcessor\nimport org.junit.platform.commons.support.AnnotationSupport.findAnnotatedFields\nimport org.junit.platform.commons.support.ModifierSupport\nimport java.lang.reflect.Field\nimport java.util.function.Predicate\n\nclass RandomNumberExtension :\n BeforeAllCallback,\n TestInstancePostProcessor,\n ParameterResolver {\n private val random = java.util.Random(System.nanoTime())\n\n /**\n * Inject a random integer into static fields that are annotated with\n * `@Random` and can be assigned an integer value.\n */\n override fun beforeAll(context: ExtensionContext) {\n val testClass = context.requiredTestClass\n injectFields(testClass, null, ModifierSupport::isStatic)\n }\n\n /**\n * Inject a random integer into non-static fields that are annotated with\n * `@Random` and can be assigned an integer value.\n */\n override fun postProcessTestInstance(\n testInstance: Any,\n context: ExtensionContext\n ) {\n val testClass = context.requiredTestClass\n injectFields(testClass, testInstance, ModifierSupport::isNotStatic)\n }\n\n /**\n * Determine if the parameter is annotated with `@Random` and can be\n * assigned an integer value.\n */\n override fun supportsParameter(\n pc: ParameterContext,\n ec: ExtensionContext\n ): Boolean = pc.isAnnotated(Random::class.java) && isInteger(pc.parameter.type)\n\n /**\n * Resolve a random integer.\n */\n override fun resolveParameter(\n pc: ParameterContext,\n ec: ExtensionContext\n ): Int = random.nextInt()\n\n private fun injectFields(\n testClass: Class<*>,\n testInstance: Any?,\n predicate: Predicate\n ) {\n val combined = predicate.and { field -> isInteger(field.type) }\n findAnnotatedFields(testClass, Random::class.java, combined)\n .forEach { field ->\n field.isAccessible = true\n field.set(testInstance, random.nextInt())\n }\n }\n\n private fun isInteger(type: Class<*>): Boolean = type == Int::class.javaObjectType || type == Int::class.javaPrimitiveType\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/registration/DocumentationDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin.registration\n\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.extension.RegisterExtension\nimport java.nio.file.Path\n\n// tag::user_guide[]\nclass DocumentationDemo {\n @JvmField\n @RegisterExtension\n val docs: DocumentationExtension =\n DocumentationExtension.forPath(lookUpDocsDir())\n\n @Test\n fun generateDocumentation() {\n // use this.docs ...\n }\n\n companion object {\n fun lookUpDocsDir(): Path? {\n // return path to docs dir\n return null\n }\n }\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/registration/DocumentationExtension.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin.registration\n\nimport org.junit.jupiter.api.extension.AfterEachCallback\nimport org.junit.jupiter.api.extension.ExtensionContext\nimport java.nio.file.Path\n\nclass DocumentationExtension private constructor(\n private val path: Path?\n) : AfterEachCallback {\n override fun afterEach(context: ExtensionContext) {\n // no-op for demo\n }\n\n companion object {\n @JvmStatic\n fun forPath(path: Path?): DocumentationExtension = DocumentationExtension(path)\n }\n}\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/testinterface/TestInterfaceDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin.testinterface\n\nimport org.junit.jupiter.api.Assertions.assertEquals\nimport org.junit.jupiter.api.Test\n\n// tag::user_guide[]\nclass TestInterfaceDemo :\n TestLifecycleLogger,\n TimeExecutionLogger,\n TestInterfaceDynamicTestsDemo {\n @Test\n fun isEqualValue() {\n assertEquals(1, \"a\".length, \"is always equal\")\n }\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/testinterface/TestInterfaceDynamicTestsDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin.testinterface\n\nimport example.util.StringUtils.isPalindrome\nimport org.junit.jupiter.api.Assertions.assertTrue\nimport org.junit.jupiter.api.DynamicTest\nimport org.junit.jupiter.api.DynamicTest.dynamicTest\nimport org.junit.jupiter.api.TestFactory\n\n// tag::user_guide[]\ninterface TestInterfaceDynamicTestsDemo {\n @TestFactory\n fun dynamicTestsForPalindromes(): Sequence =\n sequenceOf(\"racecar\", \"radar\", \"mom\", \"dad\")\n .map { text -> dynamicTest(text) { assertTrue(isPalindrome(text)) } }\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/testinterface/TestLifecycleLogger.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin.testinterface\n\nimport org.junit.jupiter.api.AfterAll\nimport org.junit.jupiter.api.AfterEach\nimport org.junit.jupiter.api.BeforeAll\nimport org.junit.jupiter.api.BeforeEach\nimport org.junit.jupiter.api.TestInfo\nimport org.junit.jupiter.api.TestInstance\nimport org.junit.jupiter.api.TestInstance.Lifecycle\nimport java.util.logging.Logger\n\n// tag::user_guide[]\n@TestInstance(Lifecycle.PER_CLASS)\ninterface TestLifecycleLogger {\n @BeforeAll\n fun beforeAllTests() {\n logger.info(\"Before all tests\")\n }\n\n @AfterAll\n fun afterAllTests() {\n logger.info(\"After all tests\")\n }\n\n @BeforeEach\n fun beforeEachTest(testInfo: TestInfo) {\n logger.info { \"About to execute [${testInfo.displayName}]\" }\n }\n\n @AfterEach\n fun afterEachTest(testInfo: TestInfo) {\n logger.info { \"Finished executing [${testInfo.displayName}]\" }\n }\n\n companion object {\n private val logger: Logger = Logger.getLogger(TestLifecycleLogger::class.java.name)\n }\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/testinterface/TimeExecutionLogger.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin.testinterface\n\nimport example.timing.TimingExtension\nimport org.junit.jupiter.api.Tag\nimport org.junit.jupiter.api.extension.ExtendWith\n\n// tag::user_guide[]\n@Tag(\"timed\")\n@ExtendWith(TimingExtension::class)\ninterface TimeExecutionLogger\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/timing/TimingExtension.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin.timing\n\n// tag::user_guide[]\nimport org.junit.jupiter.api.extension.AfterTestExecutionCallback\nimport org.junit.jupiter.api.extension.BeforeTestExecutionCallback\nimport org.junit.jupiter.api.extension.ExtensionContext\nimport org.junit.jupiter.api.extension.ExtensionContext.Namespace\nimport org.junit.jupiter.api.extension.ExtensionContext.Store\nimport java.util.logging.Logger\n\n// end::user_guide[]\n\n// tag::user_guide[]\nclass TimingExtension :\n BeforeTestExecutionCallback,\n AfterTestExecutionCallback {\n override fun beforeTestExecution(context: ExtensionContext) {\n getStore(context).put(START_TIME, System.currentTimeMillis())\n }\n\n override fun afterTestExecution(context: ExtensionContext) {\n val testMethod = context.requiredTestMethod\n val startTime = getStore(context).remove(START_TIME, Long::class.javaObjectType)!!\n val duration = System.currentTimeMillis() - startTime\n\n logger.info { \"Method [${testMethod.name}] took $duration ms.\" }\n }\n\n private fun getStore(context: ExtensionContext): Store = context.getStore(Namespace.create(javaClass, context.requiredTestMethod))\n\n companion object {\n private val logger: Logger = Logger.getLogger(TimingExtension::class.java.name)\n private const val START_TIME = \"start time\"\n }\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/kotlin/timing/TimingExtensionTests.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.kotlin.timing\n\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.extension.ExtendWith\n\n// tag::user_guide[]\n@ExtendWith(TimingExtension::class)\nclass TimingExtensionTests {\n @Test\n fun sleep20ms() {\n Thread.sleep(20)\n }\n\n @Test\n fun sleep50ms() {\n Thread.sleep(50)\n }\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/kotlin/example/registration/KotlinWebServerDemo.kt",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage example.registration\n\nimport org.junit.jupiter.api.Assertions.assertEquals\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.extension.RegisterExtension\n\n// tag::user_guide[]\nclass KotlinWebServerDemo {\n companion object {\n @JvmField\n @RegisterExtension\n val server =\n WebServerExtension\n .builder()\n .enableSecurity(false)\n .build()!!\n }\n\n @Test\n fun getProductList() {\n // Use WebClient to connect to web server using serverUrl and verify response\n val webClient = WebClient()\n val serverUrl = server.serverUrl\n assertEquals(200, webClient.get(\"$serverUrl/products\").responseStatus)\n }\n}\n// end::user_guide[]\n"
},
{
"path": "documentation/src/test/resources/META-INF/services/org.junit.platform.launcher.LauncherSessionListener",
"content": "example.session.GlobalSetupTeardownListener\n"
},
{
"path": "documentation/src/test/resources/junit-platform.properties",
"content": "junit.jupiter.execution.parallel.enabled=true\njunit.jupiter.execution.parallel.mode.default=concurrent\njunit.jupiter.execution.parallel.config.executor-service=worker_thread_pool\njunit.jupiter.execution.parallel.config.strategy=fixed\njunit.jupiter.execution.parallel.config.fixed.parallelism=6\n\njunit.platform.stacktrace.pruning.enabled=false\n"
},
{
"path": "documentation/src/test/resources/log4j2-test.xml",
"content": "\n\n\t\n\t\t\n\t\t\t \n\t \n\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\t\n\t\t \n\t \n \n"
},
{
"path": "documentation/src/test/resources/two-column.csv",
"content": "COUNTRY, REFERENCE\nSweden, 1\nPoland, 2\n\"United States of America\", 3\nFrance, 700_000\n"
},
{
"path": "documentation/src/tools/java/org/junit/api/tools/AbstractApiReportWriter.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage org.junit.api.tools;\n\nimport static java.util.stream.Collectors.groupingBy;\nimport static java.util.stream.Collectors.toList;\n\nimport java.io.PrintWriter;\nimport java.util.List;\nimport java.util.Map;\nimport java.util.Set;\nimport java.util.TreeMap;\n\nimport org.apiguardian.api.API.Status;\n\n/**\n * @since 1.0\n */\nabstract class AbstractApiReportWriter implements ApiReportWriter {\n\n\tprotected static final int NAME_COLUMN_WIDTH = 128;\n\n\tprivate final ApiReport apiReport;\n\n\tAbstractApiReportWriter(ApiReport apiReport) {\n\t\tthis.apiReport = apiReport;\n\t}\n\n\t@Override\n\tpublic void printReportHeader(PrintWriter out) {\n\t\tout.println(h1(\"@API Declarations\"));\n\t\tout.println();\n\t\tout.println(paragraph(\n\t\t\t\"Discovered %d types with %s declarations.\".formatted(this.apiReport.types().size(), code(\"@API\"))));\n\t\tout.println();\n\t}\n\n\t@Override\n\tpublic void printDeclarationInfo(PrintWriter out, Set statuses) {\n\t\tstatuses.forEach(\n\t\t\tstatus -> printDeclarationSection(statuses, status, this.apiReport.declarations().get(status), out));\n\t}\n\n\tprotected void printDeclarationSection(Set statuses, Status status, List declarations,\n\t\t\tPrintWriter out) {\n\t\tprintDeclarationSectionHeader(statuses, status, declarations, out);\n\t\tMap> declarationsByModule = declarations.stream() //\n\t\t\t\t.collect(groupingBy(Declaration::moduleName, TreeMap::new, toList()));\n\t\tif (declarationsByModule.isEmpty()) {\n\t\t\tout.println(paragraph(\"NOTE: There are currently no APIs annotated with %s.\".formatted(\n\t\t\t\tcode(\"@API(status = %s)\".formatted(status.name())))));\n\t\t\treturn;\n\t\t}\n\t\tdeclarationsByModule.forEach((moduleName, moduleDeclarations) -> {\n\t\t\tout.println(h3(\"Module \" + moduleName));\n\t\t\tout.println();\n\t\t\tmoduleDeclarations.stream() //\n\t\t\t\t\t.collect(groupingBy(Declaration::packageName, TreeMap::new, toList())) //\n\t\t\t\t\t.forEach((packageName, packageDeclarations) -> {\n\t\t\t\t\t\tout.println(h4(\"Package \" + packageName));\n\t\t\t\t\t\tout.println();\n\t\t\t\t\t\tprintDeclarationTableHeader(out);\n\t\t\t\t\t\tpackageDeclarations.forEach(it -> printDeclarationTableRow(it, out));\n\t\t\t\t\t\tprintDeclarationTableFooter(out);\n\t\t\t\t\t\tout.println();\n\t\t\t\t\t});\n\t\t});\n\t}\n\n\tprotected void printDeclarationSectionHeader(Set statuses, Status status, List declarations,\n\t\t\tPrintWriter out) {\n\t\tif (statuses.size() < 2) {\n\t\t\t// omit section header when only a single status is printed\n\t\t\treturn;\n\t\t}\n\t\tout.println(h2(\"@API(%s)\".formatted(status)));\n\t\tout.println();\n\t\tout.println(paragraph(\n\t\t\t\"Discovered %d %s declarations.\".formatted(declarations.size(), code(\"@API(%s)\".formatted(status)))));\n\t\tout.println();\n\t}\n\n\tprotected abstract String h1(String header);\n\n\tprotected abstract String h2(String header);\n\n\tprotected abstract String h3(String header);\n\n\tprotected abstract String h4(String header);\n\n\tprotected abstract String code(String element);\n\n\tprotected abstract String italic(String element);\n\n\tprotected String paragraph(String element) {\n\t\treturn element;\n\t}\n\n\tprotected abstract void printDeclarationTableHeader(PrintWriter out);\n\n\tprotected abstract void printDeclarationTableRow(Declaration declaration, PrintWriter out);\n\n\tprotected abstract void printDeclarationTableFooter(PrintWriter out);\n\n}\n"
},
{
"path": "documentation/src/tools/java/org/junit/api/tools/ApiReport.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage org.junit.api.tools;\n\nimport java.util.List;\nimport java.util.Map;\nimport java.util.SortedSet;\n\nimport io.github.classgraph.ClassInfo;\n\nimport org.apiguardian.api.API.Status;\n\n/**\n * @since 1.0\n */\nrecord ApiReport(SortedSet types, Map> declarations) {\n}\n"
},
{
"path": "documentation/src/tools/java/org/junit/api/tools/ApiReportGenerator.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage org.junit.api.tools;\n\nimport static java.nio.charset.StandardCharsets.UTF_8;\nimport static java.util.stream.Collectors.toCollection;\nimport static java.util.stream.Collectors.toUnmodifiableSet;\n\nimport java.io.BufferedOutputStream;\nimport java.io.File;\nimport java.io.IOException;\nimport java.io.OutputStream;\nimport java.io.PrintWriter;\nimport java.io.UncheckedIOException;\nimport java.lang.module.ModuleFinder;\nimport java.nio.file.Files;\nimport java.nio.file.Path;\nimport java.util.ArrayList;\nimport java.util.Arrays;\nimport java.util.EnumMap;\nimport java.util.EnumSet;\nimport java.util.List;\nimport java.util.Map;\nimport java.util.SortedSet;\nimport java.util.TreeSet;\nimport java.util.stream.Stream;\n\nimport io.github.classgraph.ClassGraph;\nimport io.github.classgraph.ClassInfo;\nimport io.github.classgraph.MethodInfo;\nimport io.github.classgraph.ScanResult;\n\nimport org.apiguardian.api.API;\nimport org.apiguardian.api.API.Status;\nimport org.junit.platform.commons.logging.Logger;\nimport org.junit.platform.commons.logging.LoggerFactory;\n\n/**\n * @since 1.0\n */\nclass ApiReportGenerator {\n\n\tprivate static final Logger logger = LoggerFactory.getLogger(ApiReportGenerator.class);\n\tprivate static final String EOL = System.lineSeparator();\n\n\tpublic static void main(String... args) {\n\n\t\t// CAUTION: The output produced by this method is used to\n\t\t// generate a table in the User Guide.\n\n\t\ttry (var scanResult = scanClasspath()) {\n\n\t\t\tvar apiReport = generateReport(scanResult);\n\n\t\t\t// ApiReportWriter reportWriter = new MarkdownApiReportWriter(apiReport);\n\t\t\tApiReportWriter reportWriter = new AsciidocApiReportWriter(apiReport);\n\t\t\t// ApiReportWriter reportWriter = new HtmlApiReportWriter(apiReport);\n\n\t\t\t// reportWriter.printReportHeader(new PrintWriter(System.out, true));\n\n\t\t\t// Print report for all Usage enum constants\n\t\t\t// reportWriter.printDeclarationInfo(new PrintWriter(System.out, true), EnumSet.allOf(Status.class));\n\n\t\t\t// Print report only for specific Status constants, defaults to only EXPERIMENTAL\n\t\t\tparseArgs(args).forEach((status, opener) -> {\n\t\t\t\ttry (var stream = opener.openStream()) {\n\t\t\t\t\tvar writer = new PrintWriter(stream == null ? System.out : stream, true, UTF_8);\n\t\t\t\t\treportWriter.printDeclarationInfo(writer, EnumSet.of(status));\n\t\t\t\t}\n\t\t\t\tcatch (IOException e) {\n\t\t\t\t\tthrow new UncheckedIOException(\"Failed to write report\", e);\n\t\t\t\t}\n\t\t\t});\n\t\t}\n\t}\n\n\t// -------------------------------------------------------------------------\n\n\tprivate static Map parseArgs(String[] args) {\n\t\tMap outputByStatus = new EnumMap<>(Status.class);\n\t\tif (args.length == 0) {\n\t\t\toutputByStatus.put(Status.EXPERIMENTAL, () -> null);\n\t\t}\n\t\telse {\n\t\t\tArrays.stream(args) //\n\t\t\t\t\t.map(arg -> arg.split(\"=\", 2)) //\n\t\t\t\t\t.forEach(parts -> outputByStatus.put(//\n\t\t\t\t\t\tStatus.valueOf(parts[0]), //\n\t\t\t\t\t\t() -> parts.length < 2 //\n\t\t\t\t\t\t\t\t? null //\n\t\t\t\t\t\t\t\t: new BufferedOutputStream(Files.newOutputStream(Path.of(parts[1]))) //\n\t\t\t\t\t));\n\t\t}\n\t\treturn outputByStatus;\n\t}\n\n\tprivate interface StreamOpener {\n\t\tOutputStream openStream() throws IOException;\n\t}\n\n\tprivate static ApiReport generateReport(ScanResult scanResult) {\n\t\tMap> declarations = new EnumMap<>(Status.class);\n\t\tfor (var status : Status.values()) {\n\t\t\tdeclarations.put(status, new ArrayList<>());\n\t\t}\n\n\t\tvar types = collectTypes(scanResult);\n\t\ttypes.stream() //\n\t\t\t\t.map(Declaration.Type::new) //\n\t\t\t\t.forEach(type -> declarations.get(type.status()).add(type));\n\n\t\tcollectMethods(scanResult) //\n\t\t\t\t.map(Declaration.Method::new) //\n\t\t\t\t.filter(method -> !declarations.get(method.status()) //\n\t\t\t\t\t\t.contains(new Declaration.Type(method.classInfo()))) //\n\t\t\t\t.forEach(method -> {\n\t\t\t\t\ttypes.add(method.classInfo());\n\t\t\t\t\tdeclarations.get(method.status()).add(method);\n\t\t\t\t});\n\n\t\tdeclarations.values().forEach(list -> list.sort(null));\n\n\t\treturn new ApiReport(types, declarations);\n\t}\n\n\tprivate static ScanResult scanClasspath() {\n\t\t// scan all types below \"org.junit\" package\n\t\tvar classGraph = new ClassGraph() //\n\t\t\t\t.acceptPackages(\"org.junit\") //\n\t\t\t\t.rejectPackages(\"*.shadow.*\", \"org.opentest4j.*\", \"org.junit.platform.commons.logging\",\n\t\t\t\t\t\"org.junit.platform.commons.util\") //\n\t\t\t\t.disableNestedJarScanning() //\n\t\t\t\t.enableClassInfo() //\n\t\t\t\t.enableMethodInfo() //\n\t\t\t\t.enableAnnotationInfo(); //\n\t\tvar apiClasspath = System.getProperty(\"api.modulePath\");\n\t\tvar apiModules = System.getProperty(\"api.moduleNames\");\n\t\tif (apiClasspath != null && apiModules != null) {\n\t\t\tvar paths = Arrays.stream(apiClasspath.split(File.pathSeparator)).map(Path::of).toArray(Path[]::new);\n\t\t\tvar bootLayer = ModuleLayer.boot();\n\t\t\tvar roots = Arrays.stream(apiModules.split(\",\")).collect(toUnmodifiableSet());\n\t\t\tvar configuration = bootLayer.configuration().resolveAndBind(ModuleFinder.of(), ModuleFinder.of(paths),\n\t\t\t\troots);\n\t\t\tvar layer = bootLayer.defineModulesWithOneLoader(configuration, ClassLoader.getPlatformClassLoader());\n\t\t\tclassGraph = classGraph.overrideModuleLayers(layer);\n\t\t}\n\t\treturn classGraph.scan();\n\t}\n\n\tprivate static SortedSet collectTypes(ScanResult scanResult) {\n\t\tvar types = scanResult.getClassesWithAnnotation(API.class).stream() //\n\t\t\t\t.filter(it -> !it.getAnnotationInfo(API.class).isInherited()) //\n\t\t\t\t.collect(toCollection(TreeSet::new));\n\n\t\tlogger.debug(() -> {\n\t\t\tvar builder = new StringBuilder(\"Listing of all \" + types.size() + \" annotated types:\");\n\t\t\tbuilder.append(EOL);\n\t\t\ttypes.forEach(e -> builder.append(e.getName()).append(EOL));\n\t\t\treturn builder.toString();\n\t\t});\n\n\t\treturn types;\n\t}\n\n\tprivate static Stream collectMethods(ScanResult scanResult) {\n\t\treturn scanResult.getClassesWithMethodAnnotation(API.class).stream() //\n\t\t\t\t.flatMap(type -> type.getDeclaredMethodAndConstructorInfo().stream()) //\n\t\t\t\t.filter(m -> m.getAnnotationInfo(API.class) != null);\n\t}\n\n\tprivate ApiReportGenerator() {\n\t}\n\n}\n"
},
{
"path": "documentation/src/tools/java/org/junit/api/tools/ApiReportWriter.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage org.junit.api.tools;\n\nimport java.io.PrintWriter;\nimport java.util.Set;\n\nimport org.apiguardian.api.API.Status;\n\n/**\n * @since 1.0\n */\ninterface ApiReportWriter {\n\n\tvoid printReportHeader(PrintWriter out);\n\n\tvoid printDeclarationInfo(PrintWriter out, Set statuses);\n\n}\n"
},
{
"path": "documentation/src/tools/java/org/junit/api/tools/AsciidocApiReportWriter.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage org.junit.api.tools;\n\nimport java.io.PrintWriter;\n\n/**\n * @since 1.0\n */\nclass AsciidocApiReportWriter extends AbstractApiReportWriter {\n\n\tprivate static final String ASCIIDOC_FORMAT = \"|%-\" + NAME_COLUMN_WIDTH + \"s | %-12s%n\";\n\n\tAsciidocApiReportWriter(ApiReport apiReport) {\n\t\tsuper(apiReport);\n\t}\n\n\t@Override\n\tprotected String h1(String header) {\n\t\treturn \"= \" + header;\n\t}\n\n\t@Override\n\tprotected String h2(String header) {\n\t\treturn \"== \" + header;\n\t}\n\n\t@Override\n\tprotected String h3(String header) {\n\t\treturn \"%n=== %s\".formatted(header);\n\t}\n\n\t@Override\n\tprotected String h4(String header) {\n\t\treturn \"%n==== %s\".formatted(header);\n\t}\n\n\t@Override\n\tprotected String code(String element) {\n\t\treturn \"`\" + element + \"`\";\n\t}\n\n\t@Override\n\tprotected String italic(String element) {\n\t\treturn \"_\" + element + \"_\";\n\t}\n\n\t@Override\n\tprotected void printDeclarationTableHeader(PrintWriter out) {\n\t\tout.println(\"[cols=\\\"99,1\\\"]\");\n\t\tout.println(\"|===\");\n\t\tout.printf(ASCIIDOC_FORMAT, \"Name\", \"Since\");\n\t\tout.println();\n\t}\n\n\t@Override\n\tprotected void printDeclarationTableRow(Declaration declaration, PrintWriter out) {\n\t\tout.printf(ASCIIDOC_FORMAT, //\n\t\t\tcode(declaration.name().replace(\".\", \".\")) + \" \" + italic(\"(\" + declaration.kind() + \")\"), //\n\t\t\tcode(declaration.since()) //\n\t\t);\n\t}\n\n\t@Override\n\tprotected void printDeclarationTableFooter(PrintWriter out) {\n\t\tout.println(\"|===\");\n\t}\n\n}\n"
},
{
"path": "documentation/src/tools/java/org/junit/api/tools/Declaration.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage org.junit.api.tools;\n\nimport static java.util.stream.Collectors.joining;\n\nimport java.util.Arrays;\n\nimport io.github.classgraph.AnnotationEnumValue;\nimport io.github.classgraph.AnnotationParameterValueList;\nimport io.github.classgraph.ClassInfo;\nimport io.github.classgraph.MethodInfo;\n\nimport org.apiguardian.api.API;\nimport org.apiguardian.api.API.Status;\n\nsealed interface Declaration extends Comparable {\n\n\tString moduleName();\n\n\tString packageName();\n\n\tString fullName();\n\n\tString name();\n\n\tString kind();\n\n\tStatus status();\n\n\tString since();\n\n\t@Override\n\tdefault int compareTo(Declaration o) {\n\t\treturn fullName().compareTo(o.fullName());\n\t}\n\n\trecord Type(ClassInfo classInfo) implements Declaration {\n\n\t\t@Override\n\t\tpublic String moduleName() {\n\t\t\treturn classInfo.getModuleRef().getName();\n\t\t}\n\n\t\t@Override\n\t\tpublic String packageName() {\n\t\t\treturn classInfo.getPackageName();\n\t\t}\n\n\t\t@Override\n\t\tpublic String fullName() {\n\t\t\treturn classInfo.getName();\n\t\t}\n\n\t\t@Override\n\t\tpublic String name() {\n\t\t\tvar shortClassName = getShortClassName(classInfo);\n\t\t\treturn classInfo.isAnnotation() ? \"@\" + shortClassName : shortClassName;\n\t\t}\n\n\t\t@Override\n\t\tpublic String kind() {\n\t\t\treturn switch (classInfo) {\n\t\t\t\tcase ClassInfo ignored when classInfo.isRecord() -> \"record\";\n\t\t\t\tcase ClassInfo ignored when classInfo.isAnnotation() -> \"annotation\";\n\t\t\t\tcase ClassInfo ignored when classInfo.isEnum() -> \"enum\";\n\t\t\t\tcase ClassInfo ignored when classInfo.isInterface() -> \"interface\";\n\t\t\t\tdefault -> \"class\";\n\t\t\t};\n\t\t}\n\n\t\t@Override\n\t\tpublic Status status() {\n\t\t\treturn readStatus(getParameterValues());\n\t\t}\n\n\t\t@Override\n\t\tpublic String since() {\n\t\t\treturn readSince(getParameterValues());\n\t\t}\n\n\t\tprivate AnnotationParameterValueList getParameterValues() {\n\t\t\treturn classInfo.getAnnotationInfo(API.class).getParameterValues();\n\t\t}\n\t}\n\n\trecord Method(MethodInfo methodInfo) implements Declaration {\n\n\t\t@Override\n\t\tpublic String moduleName() {\n\t\t\treturn classInfo().getModuleRef().getName();\n\t\t}\n\n\t\t@Override\n\t\tpublic String packageName() {\n\t\t\treturn classInfo().getPackageName();\n\t\t}\n\n\t\t@Override\n\t\tpublic String fullName() {\n\t\t\treturn \"%s.%s\".formatted(classInfo().getName(), methodSignature());\n\t\t}\n\n\t\t@Override\n\t\tpublic String name() {\n\t\t\tif (classInfo().isAnnotation()) {\n\t\t\t\treturn \"@%s(%s=...)\".formatted(getShortClassName(classInfo()), methodInfo.getName());\n\t\t\t}\n\t\t\tif (methodInfo.isConstructor()) {\n\t\t\t\treturn \"%s%s\".formatted(getShortClassName(classInfo()), methodParameters());\n\t\t\t}\n\t\t\treturn \"%s.%s\".formatted(getShortClassName(classInfo()), methodSignature());\n\t\t}\n\n\t\tprivate String methodSignature() {\n\t\t\treturn methodInfo.getName() + methodParameters();\n\t\t}\n\n\t\tprivate String methodParameters() {\n\t\t\treturn Arrays.stream(methodInfo.getParameterInfo()) //\n\t\t\t\t\t.map(parameterInfo -> parameterInfo.getTypeSignatureOrTypeDescriptor().toStringWithSimpleNames()) //\n\t\t\t\t\t.collect(joining(\", \", \"(\", \")\"));\n\t\t}\n\n\t\t@Override\n\t\tpublic String kind() {\n\t\t\tif (methodInfo.isConstructor()) {\n\t\t\t\treturn \"constructor\";\n\t\t\t}\n\t\t\tif (classInfo().isAnnotation()) {\n\t\t\t\treturn \"annotation attribute\";\n\t\t\t}\n\t\t\treturn \"method\";\n\t\t}\n\n\t\t@Override\n\t\tpublic Status status() {\n\t\t\treturn readStatus(getParameterValues());\n\t\t}\n\n\t\t@Override\n\t\tpublic String since() {\n\t\t\treturn readSince(getParameterValues());\n\t\t}\n\n\t\tprivate AnnotationParameterValueList getParameterValues() {\n\t\t\treturn methodInfo.getAnnotationInfo(API.class).getParameterValues();\n\t\t}\n\n\t\tpublic ClassInfo classInfo() {\n\t\t\treturn methodInfo.getClassInfo();\n\t\t}\n\t}\n\n\tprivate static Status readStatus(AnnotationParameterValueList parameterValues) {\n\t\treturn Status.valueOf(((AnnotationEnumValue) parameterValues.getValue(\"status\")).getValueName());\n\t}\n\n\tprivate static String readSince(AnnotationParameterValueList parameterValues) {\n\t\treturn (String) parameterValues.getValue(\"since\");\n\t}\n\n\tprivate static String getShortClassName(ClassInfo classInfo) {\n\t\tvar typeName = classInfo.getName();\n\t\tvar packageName = classInfo.getPackageName();\n\t\tif (typeName.startsWith(packageName + '.')) {\n\t\t\ttypeName = typeName.substring(packageName.length() + 1);\n\t\t}\n\t\treturn typeName.replace('$', '.');\n\t}\n}\n"
},
{
"path": "documentation/src/tools/java/org/junit/api/tools/HtmlApiReportWriter.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage org.junit.api.tools;\n\nimport java.io.PrintWriter;\n\n/**\n * @since 1.0\n */\nclass HtmlApiReportWriter extends AbstractApiReportWriter {\n\n\tprivate static final String HTML_HEADER_FORMAT = \"\\t%s %s %s %s \" + header + \" \";\n\t}\n\n\t@Override\n\tprotected String h2(String header) {\n\t\treturn \"\" + header + \" \";\n\t}\n\n\t@Override\n\tprotected String h3(String header) {\n\t\treturn \"\" + header + \" \";\n\t}\n\n\t@Override\n\tprotected String h4(String header) {\n\t\treturn \"\" + header + \" \";\n\t}\n\n\t@Override\n\tprotected String code(String element) {\n\t\treturn \"\" + element + \" \";\n\t}\n\n\t@Override\n\tprotected String italic(String element) {\n\t\treturn \"\" + element + \" \";\n\t}\n\n\t@Override\n\tprotected String paragraph(String element) {\n\t\treturn \"\" + element + \"
\";\n\t}\n\n\t@Override\n\tprotected void printDeclarationTableHeader(PrintWriter out) {\n\t\tout.println(\"\");\n\t\tout.printf(HTML_HEADER_FORMAT, \"Name\", \"Since\");\n\t}\n\n\t@Override\n\tprotected void printDeclarationTableRow(Declaration declaration, PrintWriter out) {\n\t\tout.printf(HTML_ROW_FORMAT, //\n\t\t\tcode(declaration.name()) + \" \" + italic(\"(\" + declaration.kind() + \")\"), //\n\t\t\tcode(declaration.since()) //\n\t\t);\n\t}\n\n\t@Override\n\tprotected void printDeclarationTableFooter(PrintWriter out) {\n\t\tout.println(\"
\");\n\t}\n\n}\n"
},
{
"path": "documentation/src/tools/java/org/junit/api/tools/MarkdownApiReportWriter.java",
"content": "/*\n * Copyright 2015-2026 the original author or authors.\n *\n * All rights reserved. This program and the accompanying materials are\n * made available under the terms of the Eclipse Public License v2.0 which\n * accompanies this distribution and is available at\n *\n * https://www.eclipse.org/legal/epl-v20.html\n */\n\npackage org.junit.api.tools;\n\nimport java.io.PrintWriter;\nimport java.nio.CharBuffer;\n\n/**\n * @since 1.0\n */\nclass MarkdownApiReportWriter extends AbstractApiReportWriter {\n\n\tprivate static final String MARKDOWN_FORMAT = \"%-\" + NAME_COLUMN_WIDTH + \"s | %-12s%n\";\n\n\tMarkdownApiReportWriter(ApiReport apiReport) {\n\t\tsuper(apiReport);\n\t}\n\n\t@Override\n\tprotected String h1(String header) {\n\t\treturn \"# \" + header;\n\t}\n\n\t@Override\n\tprotected String h2(String header) {\n\t\treturn \"## \" + header;\n\t}\n\n\t@Override\n\tprotected String h3(String header) {\n\t\treturn \"### \" + header;\n\t}\n\n\t@Override\n\tprotected String h4(String header) {\n\t\treturn \"#### \" + header;\n\t}\n\n\t@Override\n\tprotected String code(String element) {\n\t\treturn \"`\" + element + \"`\";\n\t}\n\n\t@Override\n\tprotected String italic(String element) {\n\t\treturn \"_\" + element + \"_\";\n\t}\n\n\t@Override\n\tprotected void printDeclarationTableHeader(PrintWriter out) {\n\t\tout.printf(MARKDOWN_FORMAT, \"Name\", \"Since\");\n\t\tout.printf(MARKDOWN_FORMAT, dashes(NAME_COLUMN_WIDTH), dashes(12));\n\t}\n\n\tprivate String dashes(int length) {\n\t\treturn CharBuffer.allocate(length).toString().replace('\\0', '-');\n\t}\n\n\t@Override\n\tprotected void printDeclarationTableRow(Declaration declaration, PrintWriter out) {\n\t\tout.printf(MARKDOWN_FORMAT, //\n\t\t\tcode(declaration.name()) + \" \" + italic(\"(\" + declaration.kind() + \")\"), //\n\t\t\tcode(declaration.since()) //\n\t\t);\n\t}\n\n\t@Override\n\tprotected void printDeclarationTableFooter(PrintWriter out) {\n\t\t/* no-op */\n\t}\n\n}\n"
},
{
"path": "documentation/src/tools/java/org/junit/api/tools/package-info.java",
"content": "/**\n * Tools to generate reports based on {@link org.apiguardian.api.API} annotations.\n */\n\npackage org.junit.api.tools;\n"
},
{
"path": "gradle/base/code-generator-model/.gitignore",
"content": "/bin/\n"
},
{
"path": "gradle/base/code-generator-model/build.gradle.kts",
"content": "plugins {\n `kotlin-dsl`\n}\n"
},
{
"path": "gradle/base/code-generator-model/src/main/kotlin/junitbuild/generator/model/JRE.kt",
"content": "package junitbuild.generator.model\n\ndata class JRE(val version: Int, val since: String?)\n"
},
{
"path": "gradle/base/code-generator-model/src/main/resources/jre.yaml",
"content": "- version: 8\n- version: 9\n- version: 10\n- version: 11\n- version: 12\n since: '5.4'\n- version: 13\n since: '5.4'\n- version: 14\n since: '5.5'\n- version: 15\n since: '5.6'\n- version: 16\n since: '5.7'\n- version: 17\n since: '5.7.1'\n- version: 18\n since: '5.8.1'\n- version: 19\n since: '5.9'\n- version: 20\n since: '5.9'\n- version: 21\n since: '5.9.2'\n- version: 22\n since: '5.10'\n- version: 23\n since: '5.11'\n- version: 24\n since: '5.11'\n- version: 25\n since: '5.11.4'\n- version: 26\n since: '5.13.2'\n- version: 27\n since: '6.1'\n"
},
{
"path": "gradle/base/dsl-extensions/.gitignore",
"content": "/bin/\n"
},
{
"path": "gradle/base/dsl-extensions/build.gradle.kts",
"content": "plugins {\n `kotlin-dsl`\n}\n"
},
{
"path": "gradle/base/dsl-extensions/src/main/kotlin/junitbuild/extensions/DependencyExtensions.kt",
"content": "package junitbuild.extensions\n\nimport org.gradle.api.provider.Provider\nimport org.gradle.plugin.use.PluginDependency\n\n// see https://docs.gradle.org/current/userguide/plugins.html#sec:plugin_markers\nval Provider.markerCoordinates: Provider\n get() = map { \"${it.pluginId}:${it.pluginId}.gradle.plugin:${it.version}\" }\n"
},
{
"path": "gradle/base/dsl-extensions/src/main/kotlin/junitbuild/extensions/ProjectExtensions.kt",
"content": "package junitbuild.extensions\n\nimport org.gradle.api.Project\nimport org.gradle.api.artifacts.ProjectDependency\nimport org.gradle.api.artifacts.VersionCatalog\nimport org.gradle.api.artifacts.VersionCatalogsExtension\nimport org.gradle.kotlin.dsl.the\n\nval Project.javaModuleName: String\n get() = toModuleName(name)\n\nval ProjectDependency.javaModuleName: String\n get() = toModuleName(name)\n\nprivate fun toModuleName(name: String) = \"org.${name.replace('-', '.')}\"\n\nfun Project.dependencyProject(dependency: ProjectDependency) =\n project(dependency.path)\n\nfun Project.requiredVersionFromLibs(name: String) =\n libsVersionCatalog.findVersion(name).get().requiredVersion\n\nfun Project.dependencyFromLibs(name: String) =\n libsVersionCatalog.findLibrary(name).get()\n\nfun Project.bundleFromLibs(name: String) =\n libsVersionCatalog.findBundle(name).get()\n\nprivate val Project.libsVersionCatalog: VersionCatalog\n get() = the().named(\"libs\")\n"
},
{
"path": "gradle/base/dsl-extensions/src/main/kotlin/junitbuild/extensions/StringExtensions.kt",
"content": "package junitbuild.extensions\n\nimport java.util.Locale\n\nfun String.capitalized() = replaceFirstChar {\n it.uppercase(Locale.US)\n}\n"
},
{
"path": "gradle/base/dsl-extensions/src/main/kotlin/junitbuild/extensions/TaskExtensions.kt",
"content": "package junitbuild.extensions\n\nimport org.gradle.api.Task\nimport org.gradle.api.file.ArchiveOperations\nimport org.gradle.internal.os.OperatingSystem\nimport org.gradle.kotlin.dsl.newInstance\nimport javax.inject.Inject\n\nfun Task.trackOperationSystemAsInput() =\n inputs.property(\"os\", OperatingSystem.current().familyName)\n\nfun Task.withArchiveOperations(action: (ArchiveOperations) -> T): T =\n archiveOperations.run { action(this) }\n\nprivate val Task.archiveOperations: ArchiveOperations\n get() = project.objects.newInstance(DummyObject::class).archiveOperations\n\nprivate abstract class DummyObject {\n @get:Inject\n abstract val archiveOperations: ArchiveOperations\n}\n"
},
{
"path": "gradle/base/dsl-extensions/src/main/kotlin/junitbuild/extensions/VersionExtensions.kt",
"content": "package junitbuild.extensions\n\nfun Any.isSnapshot(): Boolean = toString().contains(\"SNAPSHOT\")\n"
},
{
"path": "gradle/base/dsl-extensions/src/main/kotlin/junitbuild/extensions/junitbuild.dsl-extensions.gradle.kts",
"content": "// Just a dummy plugin to get the extensions on the classpath of downstream builds\n"
},
{
"path": "gradle/base/gradle.properties",
"content": "group = junitbuild.base\n"
},
{
"path": "gradle/base/settings.gradle.kts",
"content": "rootProject.name = \"base\"\n\ndependencyResolutionManagement {\n repositories {\n gradlePluginPortal()\n }\n}\n\ninclude(\"code-generator-model\")\ninclude(\"dsl-extensions\")\n"
},
{
"path": "gradle/config/checkstyle/checkstyleMain.xml",
"content": "\n\n\n\t\n\t\t\n\t\t\t \n\t\t\n\t\t\t \n\t\t\n\t\t\t \n\t\t\n\t\t\n\t\t\t \n\t\t\n\t\t\t\n\t\t\t\n\t\t\t\n\t\t\t\n\t\t \n\t\t\n\t\t\t\n\t\t\t\n\t\t\t\n\t\t\t\n\t\t \n\t\t\n\t\t\t\n\t\t\t\n\t\t\t\n\t\t\t\n\t\t\t\n\t\t \n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\t\n\t\t \n\t\t\n\t\t\t\n\t\t\t\n\t\t\t
![\"JUnit\"](\"https://junit.org/assets/img/junit-logo.svg\")
\n