Designs a test strategy for Adobe Experience Manager projects and writes the tests — JUnit 5 with AEM Mocks for Sling Models, OSGi services, servlets, job consumers and workflow steps; integration tests with the AEM testing clients; UI tests in Cloud Manager; front-end and Edge Delivery block tests; headless persisted-query contract tests; and the coverage and OakPAL gates.
When agents use itUse this whenever the user writes or fixes a test for AEM code, mentions AemContext, AemContextExtension, AemContextBuilder, aem-mock, ResourceResolverType (RESOURCERESOLVER_MOCK, JCR_MOCK, JCR_OAK), context.load().json, context.create().page(), MockJcr.setQueryResult, registerInjectActivateService, contentPolicyMapping, the it.tests or ui.tests module, testing.properties and ui-tests.version, REPORTS_PATH, Cypress or Playwright in Cloud Manager, JaCoCo coverage or an OakPAL failure, or asks how to test a component, dialog or content policy. Also apply when planning the test strategy for a new AEM project.
Install
Copilot (VS Code, Visual Studio, Copilot CLI and github.com) reads skills from the repository — commit them so the whole team gets them.
npx skills add AGCO-Global/org-skills --skill aem-testing -a github-copilot
# or with the org installer (adds .github/skills/aem-testing):
npx -y github:AGCO-Global/org-skills add skill aem-testing
Uses the open skills CLI. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, OpenCode, Windsurf and 60+ others — it asks which agent to install into.
Installs the aem-quality-skills plugin, which bundles all AEM / Quality skills and keeps them updated.
/plugin marketplace add AGCO-Global/org-skills
/plugin install aem-quality-skills@org-skills
# or just this skill, in this repository:
npx skills add AGCO-Global/org-skills --skill aem-testing -a claude-code
Use Download .zip above, then upload it under Customize → Skills → Upload skill. Team and Enterprise admins can sync this repo as a plugin marketplace instead.
Installs into .agents/skills/, which Codex reads.
npx skills add AGCO-Global/org-skills --skill aem-testing -a codex
Installs into Cursor's skills folder.
npx skills add AGCO-Global/org-skills --skill aem-testing -a cursor
Installs into Gemini CLI's skills folder.
npx skills add AGCO-Global/org-skills --skill aem-testing -a gemini-cli
Nothing to install. Press Download .zip above, unzip it, and drop the aem-testing folder into your tool's skills folder — .claude/skills/, .github/skills/, .cursor/skills/ or .agents/skills/. Step-by-step, per tool: How to use it. For any other tool with rules or custom prompts, Copy SKILL.md and paste it in — it is plain Markdown.
The npx commands need Node.js 20+ and use your normal git sign-in to GitHub, so they work while the repository is private. Without Node.js, see the No Node.js tab — a skill is a folder of Markdown, so copying it in works just as well.
Most AEM logic lives in Sling Models, services and servlets — test it there, fast, with AEM Mocks and realistic JSON content. Reserve slow, flake-prone instance and browser tests for what only a running AEM can prove. A test that needs a live instance to check a null-check is in the wrong layer, and a suite that takes ten minutes is a suite nobody runs before pushing.
1. Decide first
Question
Default
Change when
Which layer
The lowest one that can prove the behaviour
Servlet resolution, ACLs, repoinit, replication and rendered markup need it.tests
ResourceResolverType
RESOURCERESOLVER_MOCK
The code adapts to Node/Session → JCR_MOCK; real queries or ACLs → JCR_OAK, in one or two classes only
Content setup
A JSON fixture per test class
A shape simpler than a fixture → context.create().page()/resource()/asset()
Mocking
Mockito for outbound collaborators (HTTP, JobManager, Replicator)
Never mock Resource, ValueMap, Page or ResourceResolver — AEM Mocks gives you real ones
Testing HTL
Do not — keep logic in the model
Markup that matters is asserted in an integration test
Coverage target
~80 % on models and services
The 50 % gate is a floor, and it is overridable, which is why it is not a target
UI test scope
The few journeys that cross author and publish
Anything a unit test could prove does not belong in a browser
Where a query's correctness is proven
An integration test plus an Explain Query plan
Mocked query results prove the code around the query only
2. Layers
Layer
Tool
What it proves
Runs
Unit (most tests)
JUnit 5 + AEM Mocks + Mockito, in core
Models, services and configs, servlets, filters, job consumers, workflow steps
Every build; feeds the coverage gate
Front-end unit
Jest in ui.frontend; @web/test-runner for EDS blocks
JS modules, block DOM transformations
Maven build / the EDS repo's lint-and-test job
Package
OakPAL and the Cloud Manager rules
Filter roots and modes, /apps vs /content separation, index definitions
Code-scanning step
Integration
AEM testing clients (aem-cloud-testing-clients) in it.tests
Servlet resolution, ACLs and service users, repoinit results, replication, rendered markup
Custom functional testing, against a deployed environment
UI / E2E
Cypress (default), Playwright, WebdriverIO, Selenium in ui.tests
Author and visitor journeys end to end
Custom UI testing step
Contract
HTTP assertions against persisted queries and .model.json
The shapes consumers depend on
it.tests, or the consumer's own CI
Performance
JMeter, k6, Gatling, Lighthouse
Throughput through the CDN, page weight
Stage, scheduled — never per commit
Push every assertion as far down this table as it will go.
3. Unit tests with AEM Mocks
@ExtendWith({AemContextExtension.class, MockitoExtension.class})
class TeaserModelTest {
private final AemContext context = new AemContext(); // RESOURCERESOLVER_MOCK
@BeforeEach
void setUp() {
context.addModelsForClasses(TeaserModel.class);
context.load().json("/com/acme/core/models/TeaserModelTest.json", "/content/acme");
}
@Test
void usesPageTitleWhenTitleNotAuthored() {
context.currentResource("/content/acme/en/jcr:content/root/teaser-no-title");
TeaserModel model = context.request().adaptTo(TeaserModel.class);
assertEquals("English Home", model.getTitle());
}
}
Adapt from the same adaptable as production. A model that works from a resource in a test can still return null from the request in HTL, and the failure looks like a rendering bug.
The JSON fixture is how you test the dialog: every field appears authored and missing somewhere in it. Content policies come from context.contentPolicyMapping(...), not a hand-built /conf tree.
registerInjectActivateService performs real DS injection and calls @Activate; if a mandatory reference is missing it fails, and that is a useful test of your wiring.
Full API — AemContextBuilder, the Core Components mock plugin, context.create().page()/asset(), MockJcr.setQueryResult, Content Fragment fixtures, servlet and job patterns — is in references/aem-mocks-cookbook.md.
4. Integration, UI and contract tests
it.tests uses the AEM testing clients against a deployed environment. Create test content under a unique, test-owned path and remove it in teardown; never depend on authored production content. Poll with a timeout for async effects (replication, jobs) — never Thread.sleep.
ui.tests runs only if the module opts in: a testing.properties file containing ui-tests.version=1 next to its pom.xml. Cloud Manager builds the module into a container and passes AEM_AUTHOR_URL, AEM_PUBLISH_URL, AEM_AUTHOR_USERNAME, AEM_AUTHOR_PASSWORD and REPORTS_PATH as environment variables — read them, never hardcode a host.
Cloud Manager reads JUnit XML reports from REPORTS_PATH; it does not look at your exit code. A suite that fails loudly and writes no XML is reported as passing. This is the single most common "our UI tests are skipped" cause, alongside the missing testing.properties.
Use stable data-* selectors, not generated CSS classes. Keep the suite to the journeys that cross tiers: author a component, publish it, verify it on publish.
Headless contracts: assert the persisted query responses consumers actually call (GET /graphql/execute.json/...), including the cache headers, and snapshot the shape so a Content Fragment Model change fails a test instead of a front end. Do the same for any .model.json a consumer reads.
EDS blocks are tested with @web/test-runner against a fixture of the HTML the authoring pipeline produces — see aem-edge-delivery-services.
5. Quality gates
Coverage (JaCoCo) below the 50 % line is an Important failure: the pipeline pauses and an authorised role can override. Treat it as a floor, aim higher on models and services, and exclude generated or trivial classes explicitly in JaCoCo rather than by writing assertion-free tests.
SonarQube reliability and security findings, plus Adobe's AEM-specific rules, can be critical and stop the build. Fix rather than suppress; a suppression carries a written reason.
OakPAL / package rules: mixed packages, /libs overlays, bad index definitions, configs in unsupported folders.
Reproducing locally: run the same Maven build and the AEM Analyser Maven plugin, which covers the Cloud Service compatibility class of finding. Adobe's AEM-specific rules are not shipped as a SonarQube plugin, so a local Sonar scan reproduces only the generic rules — do not promise a team that a green local Sonar means a green pipeline.
htl-maven-plugin's validate goal compiles HTL at build time and catches syntax and expression errors before deployment. It is not a rendering test, but it is free.
Deliverable format
## Layer decision — for each behaviour: layer, and why it is not one lower
## Test classes — JUnit 5 + AEM Mocks, named <ClassUnderTest>Test, one scenario per method
## Fixtures — JSON content and policy mappings covering authored / empty / invalid dialog states
## Integration & UI — only flows needing a running AEM, with setup and teardown
## Gate notes — coverage impact, Sonar/OakPAL rules touched, JaCoCo exclusions justified
Checklist
Each behaviour is tested at the lowest layer that can prove it
The lightest ResourceResolverType that exercises the path
Models adapted from the same adaptable as production
Fixture covers authored, empty and invalid states for every dialog field
No Mockito mocks of Resource, ValueMap, Page or ResourceResolver
Error paths asserted on servlets (400, 404, 5xx without a stack trace)
Every test asserts behaviour, not just assertNotNull
it.tests content is namespaced and cleaned up; no fixed sleeps
ui.tests has testing.properties, reads the environment variables, writes JUnit XML to REPORTS_PATH
Persisted query and .model.json shapes have contract tests
No time, locale or order dependence
JaCoCo exclusions are explicit and justified
Anti-patterns
Mocking Resource or ValueMap with Mockito → load JSON into AEM Mocks; a mocked resource returns values production never would.
JCR_OAK everywhere → the lightest type per class; confine Oak to the couple of tests that need real queries.
assertNotNull(model) as the whole test → assert the value the component renders.
Business logic pushed into HTL or client JS "because the model is hard to test" → that is the model telling you it has a design problem.
UI tests that check what a unit test could → keep the browser suite to cross-tier journeys.
Thread.sleep or a hardcoded host in it.tests/ui.tests → poll with a timeout; read the environment variables.
A UI suite with no JUnit XML → Cloud Manager reports it as passed; write the reports to REPORTS_PATH.
Suppressing a Sonar or AEM rule with no reason → fix it, or write down why not, with an owner.
"Local Sonar is green, the pipeline will be too" → local Sonar lacks Adobe's AEM rules; run the AEM Analyser plugin.
Excluding real code from coverage to pass the gate → exclude generated and trivial classes only.
Go deeper
references/aem-mocks-cookbook.md — resolver types, AemContextBuilder and the Core Components plugin, content builders, MockJcr.setQueryResult, policies, service registration, servlet/job/workflow patterns, determinism.
quality-gates.md in ../../devops/aem-cloud-manager/references/ — how the gates behave in the pipeline and what the UI-test opt-in looks like from the pipeline side.
Sibling skills: aem-component-development and aem-backend-development for the code under test, aem-code-review for judging test quality in a PR, aem-performance for load testing, aem-edge-delivery-services for block tests.
---
name: aem-testing
description: >
Designs a test strategy for Adobe Experience Manager projects and writes the tests — JUnit 5 with AEM Mocks for Sling Models, OSGi services, servlets, job consumers and workflow steps; integration tests with the AEM testing clients; UI tests in Cloud Manager; front-end and Edge Delivery block tests; headless persisted-query contract tests; and the coverage and OakPAL gates. Use this whenever the user writes or fixes a test for AEM code, mentions AemContext, AemContextExtension, AemContextBuilder, aem-mock, ResourceResolverType (RESOURCERESOLVER_MOCK, JCR_MOCK, JCR_OAK), context.load().json, context.create().page(), MockJcr.setQueryResult, registerInjectActivateService, contentPolicyMapping, the it.tests or ui.tests module, testing.properties and ui-tests.version, REPORTS_PATH, Cypress or Playwright in Cloud Manager, JaCoCo coverage or an OakPAL failure, or asks how to test a component, dialog or content policy. Also apply when planning the test strategy for a new AEM project.
metadata:
technology: AEM
type: testing
---
# AEM Testing
> **Targets:** AEM as a Cloud Service 2026.x projects, JUnit 5 with io.wcm AEM Mocks, Cloud Manager quality gates · **Verified:** 2026-09 against https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/using-cloud-manager/code-quality-testing
Most AEM logic lives in Sling Models, services and servlets — test it there, fast, with AEM Mocks and realistic JSON content. Reserve slow, flake-prone instance and browser tests for what only a running AEM can prove. A test that needs a live instance to check a null-check is in the wrong layer, and a suite that takes ten minutes is a suite nobody runs before pushing.
## 1. Decide first
| Question | Default | Change when |
|---|---|---|
| Which layer | The lowest one that can prove the behaviour | Servlet resolution, ACLs, repoinit, replication and rendered markup need `it.tests` |
| `ResourceResolverType` | `RESOURCERESOLVER_MOCK` | The code adapts to `Node`/`Session` → `JCR_MOCK`; real queries or ACLs → `JCR_OAK`, in one or two classes only |
| Content setup | A JSON fixture per test class | A shape simpler than a fixture → `context.create().page()/resource()/asset()` |
| Mocking | Mockito for outbound collaborators (HTTP, `JobManager`, `Replicator`) | Never mock `Resource`, `ValueMap`, `Page` or `ResourceResolver` — AEM Mocks gives you real ones |
| Testing HTL | Do not — keep logic in the model | Markup that matters is asserted in an integration test |
| Coverage target | ~80 % on models and services | The 50 % gate is a floor, and it is overridable, which is why it is not a target |
| UI test scope | The few journeys that cross author and publish | Anything a unit test could prove does not belong in a browser |
| Where a query's correctness is proven | An integration test plus an Explain Query plan | Mocked query results prove the code *around* the query only |
## 2. Layers
| Layer | Tool | What it proves | Runs |
|---|---|---|---|
| Unit (most tests) | JUnit 5 + AEM Mocks + Mockito, in `core` | Models, services and configs, servlets, filters, job consumers, workflow steps | Every build; feeds the coverage gate |
| Front-end unit | Jest in `ui.frontend`; `@web/test-runner` for EDS blocks | JS modules, block DOM transformations | Maven build / the EDS repo's lint-and-test job |
| Package | OakPAL and the Cloud Manager rules | Filter roots and modes, `/apps` vs `/content` separation, index definitions | Code-scanning step |
| Integration | AEM testing clients (`aem-cloud-testing-clients`) in `it.tests` | Servlet resolution, ACLs and service users, repoinit results, replication, rendered markup | Custom functional testing, against a deployed environment |
| UI / E2E | Cypress (default), Playwright, WebdriverIO, Selenium in `ui.tests` | Author and visitor journeys end to end | Custom UI testing step |
| Contract | HTTP assertions against persisted queries and `.model.json` | The shapes consumers depend on | `it.tests`, or the consumer's own CI |
| Performance | JMeter, k6, Gatling, Lighthouse | Throughput through the CDN, page weight | Stage, scheduled — never per commit |
Push every assertion as far down this table as it will go.
## 3. Unit tests with AEM Mocks
```java
@ExtendWith({AemContextExtension.class, MockitoExtension.class})
class TeaserModelTest {
private final AemContext context = new AemContext(); // RESOURCERESOLVER_MOCK
@BeforeEach
void setUp() {
context.addModelsForClasses(TeaserModel.class);
context.load().json("/com/acme/core/models/TeaserModelTest.json", "/content/acme");
}
@Test
void usesPageTitleWhenTitleNotAuthored() {
context.currentResource("/content/acme/en/jcr:content/root/teaser-no-title");
TeaserModel model = context.request().adaptTo(TeaserModel.class);
assertEquals("English Home", model.getTitle());
}
}
```
- **Adapt from the same adaptable as production.** A model that works from a resource in a test can still return null from the request in HTL, and the failure looks like a rendering bug.
- The JSON fixture is how you test the **dialog**: every field appears authored and missing somewhere in it. Content policies come from `context.contentPolicyMapping(...)`, not a hand-built `/conf` tree.
- `registerInjectActivateService` performs real DS injection and calls `@Activate`; if a mandatory reference is missing it fails, and that is a useful test of your wiring.
- Full API — `AemContextBuilder`, the Core Components mock plugin, `context.create().page()/asset()`, `MockJcr.setQueryResult`, Content Fragment fixtures, servlet and job patterns — is in `references/aem-mocks-cookbook.md`.
## 4. Integration, UI and contract tests
- `it.tests` uses the AEM testing clients against a deployed environment. Create test content under a unique, test-owned path and remove it in teardown; never depend on authored production content. Poll with a timeout for async effects (replication, jobs) — never `Thread.sleep`.
- `ui.tests` runs only if the module **opts in**: a `testing.properties` file containing `ui-tests.version=1` next to its `pom.xml`. Cloud Manager builds the module into a container and passes `AEM_AUTHOR_URL`, `AEM_PUBLISH_URL`, `AEM_AUTHOR_USERNAME`, `AEM_AUTHOR_PASSWORD` and `REPORTS_PATH` as environment variables — read them, never hardcode a host.
- **Cloud Manager reads JUnit XML reports from `REPORTS_PATH`; it does not look at your exit code.** A suite that fails loudly and writes no XML is reported as passing. This is the single most common "our UI tests are skipped" cause, alongside the missing `testing.properties`.
- Use stable `data-*` selectors, not generated CSS classes. Keep the suite to the journeys that cross tiers: author a component, publish it, verify it on publish.
- **Headless contracts**: assert the persisted query responses consumers actually call (`GET /graphql/execute.json/...`), including the cache headers, and snapshot the shape so a Content Fragment Model change fails a test instead of a front end. Do the same for any `.model.json` a consumer reads.
- **EDS blocks** are tested with `@web/test-runner` against a fixture of the HTML the authoring pipeline produces — see `aem-edge-delivery-services`.
## 5. Quality gates
- **Coverage** (JaCoCo) below the 50 % line is an *Important* failure: the pipeline pauses and an authorised role can override. Treat it as a floor, aim higher on models and services, and exclude generated or trivial classes explicitly in JaCoCo rather than by writing assertion-free tests.
- **SonarQube** reliability and security findings, plus Adobe's AEM-specific rules, can be critical and stop the build. Fix rather than suppress; a suppression carries a written reason.
- **OakPAL / package rules**: mixed packages, `/libs` overlays, bad index definitions, configs in unsupported folders.
- **Reproducing locally**: run the same Maven build and the **AEM Analyser Maven plugin**, which covers the Cloud Service compatibility class of finding. Adobe's AEM-specific rules are not shipped as a SonarQube plugin, so a local Sonar scan reproduces only the generic rules — do not promise a team that a green local Sonar means a green pipeline.
- `htl-maven-plugin`'s validate goal compiles HTL at build time and catches syntax and expression errors before deployment. It is not a rendering test, but it is free.
## Deliverable format
```
## Layer decision — for each behaviour: layer, and why it is not one lower
## Test classes — JUnit 5 + AEM Mocks, named <ClassUnderTest>Test, one scenario per method
## Fixtures — JSON content and policy mappings covering authored / empty / invalid dialog states
## Integration & UI — only flows needing a running AEM, with setup and teardown
## Gate notes — coverage impact, Sonar/OakPAL rules touched, JaCoCo exclusions justified
```
## Checklist
- [ ] Each behaviour is tested at the lowest layer that can prove it
- [ ] The lightest `ResourceResolverType` that exercises the path
- [ ] Models adapted from the same adaptable as production
- [ ] Fixture covers authored, empty and invalid states for every dialog field
- [ ] No Mockito mocks of `Resource`, `ValueMap`, `Page` or `ResourceResolver`
- [ ] Error paths asserted on servlets (400, 404, 5xx without a stack trace)
- [ ] Every test asserts behaviour, not just `assertNotNull`
- [ ] `it.tests` content is namespaced and cleaned up; no fixed sleeps
- [ ] `ui.tests` has `testing.properties`, reads the environment variables, writes JUnit XML to `REPORTS_PATH`
- [ ] Persisted query and `.model.json` shapes have contract tests
- [ ] No time, locale or order dependence
- [ ] JaCoCo exclusions are explicit and justified
## Anti-patterns
- **Mocking `Resource` or `ValueMap` with Mockito** → load JSON into AEM Mocks; a mocked resource returns values production never would.
- **`JCR_OAK` everywhere** → the lightest type per class; confine Oak to the couple of tests that need real queries.
- **`assertNotNull(model)` as the whole test** → assert the value the component renders.
- **Business logic pushed into HTL or client JS "because the model is hard to test"** → that is the model telling you it has a design problem.
- **UI tests that check what a unit test could** → keep the browser suite to cross-tier journeys.
- **`Thread.sleep` or a hardcoded host in `it.tests`/`ui.tests`** → poll with a timeout; read the environment variables.
- **A UI suite with no JUnit XML** → Cloud Manager reports it as passed; write the reports to `REPORTS_PATH`.
- **Suppressing a Sonar or AEM rule with no reason** → fix it, or write down why not, with an owner.
- **"Local Sonar is green, the pipeline will be too"** → local Sonar lacks Adobe's AEM rules; run the AEM Analyser plugin.
- **Excluding real code from coverage to pass the gate** → exclude generated and trivial classes only.
## Go deeper
- `references/aem-mocks-cookbook.md` — resolver types, `AemContextBuilder` and the Core Components plugin, content builders, `MockJcr.setQueryResult`, policies, service registration, servlet/job/workflow patterns, determinism.
- `quality-gates.md` in `../../devops/aem-cloud-manager/references/` — how the gates behave in the pipeline and what the UI-test opt-in looks like from the pipeline side.
- Sibling skills: `aem-component-development` and `aem-backend-development` for the code under test, `aem-code-review` for judging test quality in a PR, `aem-performance` for load testing, `aem-edge-delivery-services` for block tests.