Testing and Debugging JSP Applications

All the examples are files of one Maven project, g7testing, deployed as g7testing.war for the browser-side checks and run without a server by the tests. It uses the usual shape of this section: the Jakarta APIs with scope provided, the JSTL implementation in the WAR, and Java 21. The page directory is the web root.

The test dependencies, all with scope test, are the ones used throughout the page. The versions are the verified ones of 2026-10-08.

The project also declares tomcat-embed-core 11.0.26, spring-webmvc and spring-test 7.0.9 and org.hamcrest:hamcrest 3.0 with the same scope, and the Surefire plugin 3.5.4.

Source: JUnit User Guide — Supported Java Versions

Source: Apache Tomcat 11 — Tomcat embedding API (Javadoc)

When a page misbehaves in a way its message cannot explain, the generated Java source is the ground truth. Jasper writes it into the scratch directory of the web application, and by default it keeps it there: the keepgenerated parameter is named like an opt-in but defaults to true.

The directory names are mechanical. The package is org.apache.jsp followed by the path of the page, and every character that is not a valid Java identifier part is escaped: a hyphen becomes _002d, so WEB-INF becomes WEB_002dINF, and the class name is the file name with _jsp appended (books_jsp). The same escaping, with _005f for an underscore, produces the long field names of tag handler pools. The file starts with a banner carrying the Tomcat version and the generation time, and its modification time is set to that of the JSP, which is how Jasper decides later whether the page changed.

The following is the part of books_jsp.java that corresponds to the Bookshelf page (the _jspService body and the tag method for the loop, with the pool bookkeeping left out). The generated file has 240 lines for a 12-line page.

Source: Apache Tomcat 11 — Jasper 2 JSP Engine How-To, Configuration

Reading it is a matter of knowing which construct produces which statement:

Two practical lessons follow from the generated source. First, a page that "does nothing" often turns out to have written its output before a failure: look for the first out.write after the failing statement. Second, when a tag does not behave, the set... calls before doStartTag show exactly which attributes Jasper passed and whether a value was evaluated as an expression (reqTime = true in the comment above the call) or taken literally. The page on the generated servlet walks through the whole structure; this page is about using it to find bugs.

Source: Jakarta Pages 4.0 — 1.1.10 Debugging JSP Pages

An error inside books_jsp.java is reported against line 178 of a file the author never wrote. The Pages specification solves this in section 11.5: a JSP 4.0 container must support the Jakarta Debugging Support for Other Languages specification, so the compiler produces class files with a SourceDebugExtension attribute that maps each line of the page to the generated Java lines. For both pages and tag files, written in standard or XML syntax, the stratum that maps to the original source is named JSP and is the default one. How to switch it on is left to the implementation; on Tomcat it is on unless suppressSmap is true.

The effect is visible in the error page for a mistyped property. /debug/typo loops over the books and prints ${b.titel}:

Jasper says line 5 and prints the page’s own lines, because the stack frame of the generated class was translated through the SMAP (the generated expression is on line 178 of typo_jsp.java). The Book record is resolved by RecordELResolver, and its message is the one to read: NoSuchMethodException: Book.titel() is the record accessor that does not exist. The table itself can be seen with javap -v on the class file in the work directory:

Each *L entry reads "input lines a,b map to output lines starting at n`", and the optional second number is a repeat count. `5:177,3 says that JSP line 5 is spread over generated lines 177 to 179 (the evaluation of ${b.titel} is on 178, inside that range), and 4:162,15 says that the c:forEach on line 4 is the whole generated method for the tag (15 lines). A debugger uses the same table in the other direction: a breakpoint on line 5 of the page becomes a breakpoint on those Java lines, and stepping advances through page lines, not generated ones. The specification adds non-normative guidelines (11.5.1) for good mappings: a breakpoint must stop before the code that translates the line, two JSP lines may share generated lines, and comments and directives are not mapped.

The same behaviour can be switched off. Declaring the jsp servlet in the web.xml of the application, with the init parameters suppressSmap=true and displaySourceFragment=false, produced the next result for the same page. There is no SourceDebugExtension in the class (javap -v finds none) and the error loses the line and the fragment, which is the reason to leave both on while developing:

Source: Jakarta Pages 4.0 — 11.5 Debugging Requirements

Source: Jakarta Debugging Support for Other Languages 2.0

Source: Apache Tomcat 11 — Jasper 2 JSP Engine How-To, Configuration

Jasper is configured with init parameters of the jsp servlet, which the global conf/web.xml declares and which an application can redeclare in its own web.xml, as the SMAP example did (verified). Every page of the application is then translated with those settings. The ones that matter for debugging, with the defaults of the Tomcat 11 documentation:

The complete table and the production values belong to Jasper Configuration & Precompilation; the rows above are only those that change what a developer sees. A parameter set on a servlet that is not named jsp does nothing, and a change to a parameter applies to pages translated after the application restarts, not to a class already compiled.

Source: Apache Tomcat 11 — Jasper 2 JSP Engine How-To, Configuration

Tomcat starts in debug mode through the jpda argument of catalina.sh. In the 11.0.26 script, jpda start adds -agentlib:jdwp=transport=dt_socket,address=localhost:8000,server=y,suspend=n to CATALINA_OPTS; the transport, address and suspend flag come from JPDA_TRANSPORT (default dt_socket), JPDA_ADDRESS (default localhost:8000) and JPDA_SUSPEND (default n), and JPDA_OPTS replaces all of them. From the IDE, a remote debug configuration to that port is attached to the running JVM:

A breakpoint set on a line of a .jsp file is resolved by the SMAP of the class, so no generated source is needed in the IDE; the IDE finds the page by the file name in the SMAP (WEB-INF/views/debug/typo.jsp above), which is why the IDE must have the web application’s sources or module configured, and why a page that the server compiled before the IDE attached still works (the class is already loaded with its table). If breakpoints in pages are ignored, the first things to check are suppressSmap and that the running class corresponds to the saved page, because a page changed on disk but not yet recompiled maps to the old lines.

The same agent works for tests. A Maven build can start the forked test JVM with a debug agent without changing the pom, through the argLine property, which is how the example below was checked (the build printed Listening for transport dt_socket at address: 5005 and ran RecentTagTest to completion); Surefire’s own -Dmaven.surefire.debug property is the short form that suspends until the IDE attaches.

For a debugger to reach a container the address must be reachable. Since JDK 9 an address of just a port listens on the loopback interface only (observed on JDK 21: 127.0.0.1:5006), so a JVM in a container needs address=*:5005 and a published port. A JDWP port is an unauthenticated remote code execution interface: bind it to the loopback or a private network, and never leave an agent configured in a production start script.

Source: Apache Tomcat 11.0.26 — catalina.sh, the jpda option

Source: Apache Maven Surefire — Debugging Tests

Source: Java Platform Debugger Architecture — Connection and Invocation Details

A JSP application has four places where a defect can live, and each one has a test that is cheap for it and a test that is not. The cheap tests find most defects; the browser tests exist because the last mile (the rendered page) is what the user sees and only they test it.

The rendered-view layer is the one specific to JSP, and is the one most projects skip: a compile error in a page, a missing tag library or an EL typo with errorOnELNotFound on, are only found when Jasper has translated the page, which otherwise happens on the first request of production.

Source: JUnit User Guide

A servlet that forwards to a view has a simple contract: it puts a model in the request and forwards. The Jakarta Servlet API is made of interfaces (HttpServletRequest, HttpServletResponse, RequestDispatcher), so Mockito can replace the container. Giving the servlet a constructor that takes its collaborator (here a BookRepository), next to the public no-argument constructor the container needs, keeps it testable without a server.

The servlet’s doGet is protected, which is why the test sits in the same package as the servlet. The test checks three facts that are all part of the controller’s contract: the attribute name the page will use (books), its value, and the exact view path. Spring’s MockHttpServletRequest and MockHttpServletResponse (in spring-test) are an alternative to Mockito that is a real implementation of the interfaces and is useful when the code reads parameters or headers; a servlet that only sets attributes is faster to write with mocks.

Source: Mockito

Source: JUnit User Guide

A classic or simple tag handler is a Java class, and the container’s part of its contract (the JspContext, the JspWriter) is again made of types that can be replaced. The Bookshelf’s RecentTag marks books published since a given year:

The container calls setJspContext before doTag, and the test does the same; the mocked JspWriter copies what is written into a StringWriter. A handler that uses the body (getJspBody().invoke(...)) can be tested the same way with a mocked JspFragment. What this does not test is the declaration: the tag library descriptor, the attribute types and the body-content are exercised only when a page uses the tag, which is the next layer (Tag Library Descriptors & EL Functions lists what the descriptor must say).

Source: Jakarta Pages 4.0 Javadoc — SimpleTagSupport

The strongest JSP-specific test starts the application in an embedded Tomcat, so that the same Jasper that production uses translates, compiles and runs the page. The embedded Tomcat uses the Tomcat artifacts as ordinary dependencies (tomcat-embed-core and tomcat-embed-jasper, here at 11.0.26, the same as the server) and is controlled by the Tomcat class. The helper starts the webapp on port 0, so the operating system picks a free port and tests can run in parallel with a server on 8080:

Four details of this helper are the ones that otherwise cost an afternoon. The document base is the source directory src/main/webapp, so the page is the one in the repository and not a copy; the compiled classes are mounted as a pre-resource at /WEB-INF/classes, because the webapp directory has no classes and @WebServlet annotations are found by scanning them; the Jasper options are applied to the jsp wrapper once the default web.xml configuration has created it (the CONFIGURE_START_EVENT), because a wrapper that does not exist cannot be configured earlier; and the JAR scanner has its manifest scanning turned off. The last one answers a real warning: with HtmlUnit 5.5.0 on the classpath, a dependency’s manifest lists jars (jetty-client-12.1.12.jar and four others) that are not on disk, and without setScanManifest(false) Tomcat logs WARNING: Failed to scan [file:/.../htmlunit-websocket-client/5.5.0/jetty-client-12.1.12.jar] with a stack trace for each of them, while the tests still pass.

The test then makes real HTTP requests with the JDK’s HttpClient and asserts on the response, and, because Jasper keeps the generated source, can also prove it exists:

The run printed GENERATED: target/tomcat-base/work/Tomcat/localhost/ROOT/org/apache/jsp/WEB_002dINF/views/books_jsp.java, the path listed in the first table of this page. A test of this kind fails the build for a page that does not compile and for one that returns an error status, which is the build-time check that a precompilation with JspC provides by another way (see Jasper Configuration & Precompilation). Making the failure readable matters: passing response.body() as the assertion message, as above, puts the Tomcat error report, with its page line and root cause, in the test report.

Source: Apache Tomcat 11 — Tomcat.addWebapp (Javadoc)

Source: Apache Tomcat 11 — The Jar Scanner Component, Standard Implementation

An HTTP client and string contains is fragile: a change in whitespace or attribute order breaks the assertion without changing the page. HtmlUnit is a Java library that behaves like a browser (it fetches the page, parses the HTML into a DOM and runs JavaScript with its own engine) with no browser binary, which makes it fast and suitable for the same build as the unit tests. The 5.5.0 release lives in the package org.htmlunit, not the old com.gargoylesoftware.htmlunit of the books' era.

Each test class gets its own base directory (target/tomcat-base-hu) so the work directories of two embedded servers do not collide. The test selects with XPath, counts the items and reads a normalised text, and the setting setThrowExceptionOnFailingStatusCode(true) makes a 404 or 500 fail the test with the status instead of returning an error page that the assertions then fail on in a confusing way. HtmlUnit is also the library to test a form: it can find a form, set its fields and submit it, which suits the scenario of Forms, Validation & Sessions. Its limit is that it is a simulation, with its own JavaScript engine and a CSS model that does not lay out a page.

Source: HtmlUnit — Getting Started

For what only a real engine shows (layout, scripts that need a modern browser, accessibility checks, a screenshot), Playwright for Java drives Chromium, Firefox or WebKit. The test reuses the embedded server and asserts with auto-waiting locators, which removes the sleeps that make browser tests flaky:

The test passed on this machine, which already had the Playwright 1.63 browsers installed (the run set PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 so that nothing was downloaded). On a clean machine or a CI runner the browser binaries have to be installed first, once, with the Playwright command line (mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install" in the documentation), which is why the usual practice is to run these tests in their own Maven profile or in a separate job. The tests of this layer should be few and cover journeys (search, add, save), not every page; the unit and rendered-view layers cover the pages. The tool comparison, tracing, parallel execution and CI recipes live on End-to-End Testing with Real Browsers, and issue #258 covers the three tools in depth.

Source: Playwright for Java — Installation

Source: Playwright for Java — Assertions

Source: Playwright for Java — Browsers

A Spring MVC application that uses JSP views (see Spring MVC with JSP) tests its controllers with MockMvc. A standalone set-up with an InternalResourceViewResolver, as in the application, is enough, and it shows an important limit:

The test passes with content().string(""): the response is empty, because the view is an InternalResourceView that forwards to /WEB-INF/views/books.jsp, and MockMvc records the forward (forwardedUrl) without invoking a JSP engine. The assertions available are therefore the status, the model, the view name and the forwarded URL. A test that wants the HTML of a JSP goes through the embedded-Tomcat layer above, or through a Spring Boot test with a real servlet container and TestRestTemplate or a Playwright test. (With Thymeleaf or FreeMarker the view is rendered by the template engine inside the mock environment, which is one of the reasons those engines are easier to test than JSP.) A small build detail: the MockMvc matchers are Hamcrest-based, and spring-test does not bring Hamcrest, so without org.hamcrest:hamcrest on the test classpath the compile fails with cannot access org.hamcrest.Matcher.

The general approach to testing Spring applications is covered by Unit and Integration Testing in Spring Boot, and the Java testing tools by Testing in Java.

Source: Spring Framework Reference — MockMvc

Source: Spring Framework Reference — JSP and JSTL

The suite is one mvn test (mvn -B package also builds the WAR). The result of the run on 2026-10-08, with Tomcat embedded and the browser binaries already installed:

The single-class and fast layers can be run alone with -Dtest=... (as in the debugger example), which is the loop to use while writing a page; the browser layer is for the build.

Source: Apache Maven Surefire — Debugging Tests

Source: Jakarta Pages 4.0 — 3.3.4 Unknown EL Identifiers

Source: Jakarta Pages 4.0 — Appendix C.1, Changes between JSP 4.0 and JSP 3.1

Source: Jakarta Pages 4.0 — Appendix C.2, Changes between JSP 3.1 and JSP 3.0

Web Development with JavaServer Pages (Manning, 2001, listed in the section bibliography) describes JSP 1.2 on Tomcat 4. Its container chapter introduces the debugging requirements and the generated servlet that this page builds on. The concepts are unchanged: a page is a servlet, the container keeps the source, and a line table maps it back. The tools around them are not.

Source: Jakarta Pages 4.0 — 11.5 Debugging Requirements

Source: Manning — Web Development with JavaServer Pages, Second Edition