This is an automated email from the ASF dual-hosted git repository.
cziegeler pushed a commit to branch master
in repository
https://gitbox.apache.org/repos/asf/sling-org-apache-sling-auth-form.git
The following commit(s) were added to refs/heads/master by this push:
new f87b4a1 docs: update AGENTS.md and README.md with accurate project
layout and test commands (#17)
f87b4a1 is described below
commit f87b4a19466e5cf4f3dbc28a232edaf8213689b3
Author: Carsten Ziegeler <[email protected]>
AuthorDate: Thu Jul 16 17:57:51 2026 +0200
docs: update AGENTS.md and README.md with accurate project layout and test
commands (#17)
Co-authored-by: Maia <maia@noreply>
---
AGENTS.md | 60 ++++++++++++++++++++++++++++++++++--------------------------
README.md | 54 +++++++++++++++++++++++++++++++++++++++++++-----------
2 files changed, 77 insertions(+), 37 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index 66af6e2..0c6847a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -11,15 +11,18 @@ mvn clean package
# Run unit tests only (fast)
mvn test
-# Run a single test class
+# Run a single unit test class
mvn test -Dtest=TokenStoreTest
-# Run unit + integration tests (requires a running OSGi container via Pax Exam)
+# Run unit + integration tests (Pax Exam)
mvn verify
# Run integration tests only
mvn failsafe:integration-test failsafe:verify
+# Run a single integration test class
+mvn -Dit.test=SLING10290IT failsafe:integration-test failsafe:verify
+
# Build with coverage report (JaCoCo)
mvn verify -Pjacoco-report
@@ -38,32 +41,36 @@ src/
main/
java/
org/apache/sling/auth/form/
- FormReason.java Public API enum for auth failure reasons
- package-info.java Package-level OSGi versioning annotation
+ FormReason.java Public API enum for auth failure
reasons
+ package-info.java Package-level OSGi versioning
annotation
impl/
- FormAuthenticationHandler.java Core auth handler (OSGi
@Component)
+ FormAuthenticationHandler.java Core auth handler (OSGi @Component)
FormAuthenticationHandlerConfig.java OSGi metatype config interface
- AuthenticationFormServlet.java Serves the login HTML form
- TokenStore.java HMAC token generation/validation
- FormLoginModulePlugin.java Optional Felix JAAS integration
+ AuthenticationFormServlet.java Serves the login HTML form
+ TokenStore.java HMAC token generation/validation
+ FormLoginModulePlugin.java Optional Felix JAAS integration
jaas/
- FormCredentials.java JAAS credentials holder
- FormLoginModule.java JAAS LoginModule
- JaasHelper.java Helper for optional JAAS wiring
- main/
+ FormCredentials.java JAAS credentials holder
+ FormLoginModule.java JAAS LoginModule
+ JaasHelper.java Helper for optional JAAS wiring
resources/
- OSGI-INF/l10n/ Metatype property localization
- org/.../impl/login.html Default login form template
+ OSGI-INF/l10n/ Metatype property localization
+ org/apache/sling/auth/form/impl/login.html Default login form template
test/
java/
- .../form/
+ org/apache/sling/auth/form/
FormReasonTest.java
impl/
- FormAuthenticationHandlerTest.java Unit tests (Mockito + OSGi mock)
+ FormAuthenticationHandlerTest.java Unit tests (Mockito + OSGi mock)
TokenStoreTest.java
- it/ Integration tests (Pax Exam, suffix *IT.java)
+ it/
+ AuthFormTestSupport.java
+ AuthFormClientTestSupport.java
+ SLING10290IT.java
+ SLING10421ValidDomainIT.java
+ SLING10421InvalidDomainIT.java
resources/
- exam.properties Pax Exam container config
+ exam.properties Pax Exam container config
```
# Development Patterns & Constraints
@@ -72,9 +79,9 @@ src/
- **OSGi DS annotations only**: use `org.osgi.service.component.annotations`
(`@Component`, `@Reference`, `@Activate`, etc.). Do not use Felix SCR
annotations.
- **Metatype config** via `@ObjectClassDefinition` + `@AttributeDefinition` in
a separate `*Config` `@interface`.
- **Package visibility**: public API lives in `org.apache.sling.auth.form`;
implementation classes live under `.impl` and must not be exported (enforced by
`bnd.bnd`).
-- **Import style**: static imports avoided; Jakarta Servlet API
(`jakarta.servlet.*`) is preferred over `javax.servlet.*`.
+- **Servlet APIs**: both `jakarta.servlet` and `javax.servlet` are present as
provided dependencies; prefer Jakarta APIs in new code.
- **No framework-specific utilities** beyond Sling/OSGi — use
`org.apache.commons.codec` (bundled via `Conditional-Package`) and
`commons-lang3` (provided scope).
-- **Logging**: SLF4J only (`org.slf4j.Logger`).
+- **Logging**: SLF4J 2.x (`org.slf4j.Logger`) only.
- **4-space indentation**, standard Java naming conventions.
- All source files must carry the Apache License 2.0 header.
- `bnd.bnd` controls bundle manifest; do not edit `MANIFEST.MF` directly.
@@ -89,19 +96,21 @@ src/
# Testing Guidelines
-- **Unit tests**: JUnit 4 + Mockito + `org.apache.sling.testing.osgi-mock`.
Place alongside sources under `src/test/java/...impl/`.
-- **Integration tests**: Pax Exam 4 running a forked OSGi container. Class
names must end in `IT` (picked up by `maven-failsafe-plugin`). Place under
`src/test/java/.../it/`.
+- **Unit tests**: JUnit 4 + Mockito +
`org.apache.sling.testing.osgi-mock.junit4`.
+- **Integration tests**: Pax Exam 4 running a forked OSGi container with Sling
Pax Exam support.
+- Class names for integration tests must end in `IT` and live under
`src/test/java/.../it/` to be picked up by `maven-failsafe-plugin`.
- Run unit tests: `mvn test`
- Run all tests including IT: `mvn verify`
- Coverage: `mvn verify -Pjacoco-report` — report in `target/site/jacoco/`.
-- Integration tests need the built JAR (`target/*.jar`) present; always run
`mvn package` before running IT tests in isolation.
+- Integration tests need the built JAR (`target/*.jar`) present; run `mvn
package` before running IT tests in isolation.
# Gotchas
- **Optional JAAS integration**: `FormLoginModulePlugin` and `jaas/` classes
depend on `org.apache.felix.jaas` and `oak-core`, both `optional` in scope.
Guard with null checks / `JaasHelper.isAvailable()`.
- **Token store file**: `TokenStore` writes a secret key file to the
filesystem path configured in `FormAuthenticationHandlerConfig`. In tests, this
path must be writable and cleaned up.
-- **Cookie vs session storage**: default is cookie (`sling.formauth` cookie).
Session storage mode stores the token in `HttpSession` — remember this affects
clustering behaviour.
-- **Integration test isolation**: each `*IT` class starts its own Pax Exam
container; running multiple IT classes in the same JVM causes port conflicts.
Failsafe forks a new JVM per test class by default — do not change this.
+- **Cookie vs session storage**: default is cookie (`sling.formauth` cookie).
Session storage mode stores the token in `HttpSession` — remember this affects
clustering behavior.
+- **Integration test isolation**: each `*IT` class starts its own Pax Exam
container; running multiple IT classes in the same JVM can cause port conflicts.
+- **Failsafe wiring**: integration test and verify goals are bound via
`maven-failsafe-plugin`; keep this when adjusting test execution phases.
- **`Conditional-Package`**: `commons-codec` classes are inlined into the
bundle (see `bnd.bnd`). Do not add a runtime `Import-Package` for
`org.apache.commons.codec`.
- **Java version**: the parent POM pins `sling.java.version=17`; do not use
`--release` flags lower than 17 in compiler args.
@@ -110,4 +119,3 @@ src/
<!-- sling-security-default:start -->
The threat model for this project is
https://github.com/apache/sling/blob/master/docs/threat-model.md .
<!-- sling-security-default:end -->
-
diff --git a/README.md b/README.md
index 9f4f84c..a507320 100644
--- a/README.md
+++ b/README.md
@@ -39,8 +39,14 @@ mvn verify
# Run integration tests only
mvn failsafe:integration-test failsafe:verify
+# Run a single integration test class
+mvn -Dit.test=SLING10290IT failsafe:integration-test failsafe:verify
+
# Generate JaCoCo report
mvn verify -Pjacoco-report
+
+# Build without running tests
+mvn package -DskipTests
```
## Project layout
@@ -50,24 +56,50 @@ pom.xml Maven build descriptor
bnd.bnd OSGi bundle manifest instructions
src/
main/
- java/org/apache/sling/auth/form/
- FormReason.java
- impl/
- FormAuthenticationHandler.java
- FormAuthenticationHandlerConfig.java
- AuthenticationFormServlet.java
- TokenStore.java
- FormLoginModulePlugin.java
- jaas/
+ java/
+ org/apache/sling/auth/form/
+ FormReason.java
+ package-info.java
+ impl/
+ FormAuthenticationHandler.java
+ FormAuthenticationHandlerConfig.java
+ AuthenticationFormServlet.java
+ TokenStore.java
+ FormLoginModulePlugin.java
+ jaas/
+ FormCredentials.java
+ FormLoginModule.java
+ JaasHelper.java
resources/
OSGI-INF/l10n/
+
org.apache.sling.auth.form.impl.FormAuthenticationHandlerConfig.properties
org/apache/sling/auth/form/impl/login.html
test/
java/
- org/apache/sling/auth/form/impl/
- org/apache/sling/auth/form/it/
+ org/apache/sling/auth/form/
+ FormReasonTest.java
+ impl/
+ FormAuthenticationHandlerTest.java
+ TokenStoreTest.java
+ it/
+ AuthFormTestSupport.java
+ AuthFormClientTestSupport.java
+ SLING10290IT.java
+ SLING10421ValidDomainIT.java
+ SLING10421InvalidDomainIT.java
+ resources/
+ exam.properties
+ content/apps/sling/OrderedFolder/SLING10290IT.html
```
+## Dependencies and integration notes
+
+* OSGi DS and Metatype annotations from
`org.osgi.service.component.annotations` and
`org.osgi.service.metatype.annotations`
+* Sling integration through `org.apache.sling.auth.core` and
`org.apache.sling.api`
+* Servlet APIs for both `jakarta.servlet` and `javax.servlet` (provided scope)
+* Optional JAAS dependencies: `org.apache.felix.jaas` and `oak-core`
+* `commons-codec` is conditionally packaged into the bundle
(`Conditional-Package` in `bnd.bnd`)
+
## Documentation
This module is part of the [Apache Sling](https://sling.apache.org) project.
