Skip to content

Render Javadoc descriptions safely and ignore block tags#1258

Merged
baev merged 6 commits intomainfrom
improve-javadoc-descriptions
Apr 1, 2026
Merged

Render Javadoc descriptions safely and ignore block tags#1258
baev merged 6 commits intomainfrom
improve-javadoc-descriptions

Conversation

@baev
Copy link
Copy Markdown
Member

@baev baev commented Apr 1, 2026

Context

This fixes #1039 by changing how @Description(useJavaDoc = true) is resolved. Instead of taking raw Javadoc text and treating it like HTML, we now render the main Javadoc body into safe plain text / markdown and stop at block tags such as @param, @return, @throws, @see, @since, @version, and friends. In practice, that means Javadoc descriptions stay useful in the report, but they no longer leak metadata sections or create an XSS surface through descriptionHtml.

The new renderer supports the parts of Javadoc people actually use in descriptions: {@code}, {@literal}, {@link}, {@linkplain}, paragraphs, line breaks, lists, code spans, entities, and Unicode text. Unsupported or malformed constructs are intentionally degraded to safe text instead of being interpreted as markup. Javadoc-backed descriptions now go to description, not descriptionHtml, while explicit HTML descriptions remain unchanged. The allure.description.javadoc.separateLines option is still supported and now uses markdown-friendly line breaks.

I also added broader regression coverage around the processor and adapters, including negative cases, malformed HTML, Unicode, multiline inline tags, unsupported standard tags, and a more realistic modern Javadoc example. The current runtime coverage is in place for JUnit 4, JUnit Platform, and TestNG, and the renderer itself now has focused unit tests so future changes are easier to review.

Example:

/**
 * Verifies token refresh for expired sessions.
 *
 * <p>Use {@code refreshToken} from {@link AuthClient}.</p>
 * <ul>
 *   <li>Handles Unicode: café, Привет, 東京</li>
 *   <li>Escapes raw HTML like <script>alert(1)</script></li>
 * </ul>
 *
 * @throws IllegalStateException when refresh fails
 */
@Description(useJavaDoc = true)
@Test
void shouldRefreshExpiredSession() { ... }

Now the report description contains only the useful body content, rendered safely, and does not include the @throws section or raw HTML.

Checklist

@github-actions github-actions bot added theme:junit4 JUnit 4 related issue theme:testng TestNG related issue theme:junit-platform JUnit 5 related issue theme:descriptions-javadoc theme:core labels Apr 1, 2026
@baev baev added the type:new feature Change that add something new for end users label Apr 1, 2026
@baev baev merged commit d7733b1 into main Apr 1, 2026
6 checks passed
@baev baev deleted the improve-javadoc-descriptions branch April 1, 2026 16:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

theme:core theme:descriptions-javadoc theme:junit4 JUnit 4 related issue theme:junit-platform JUnit 5 related issue theme:testng TestNG related issue type:new feature Change that add something new for end users

Projects

None yet

Development

Successfully merging this pull request may close these issues.

🐞: Description using Javadoc includes @throws declarations

2 participants