Org Skills

aem-testing

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.

Download .zip Raw Source
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.

npx skills add AGCO-Global/org-skills --skill aem-testing
# user-level instead of project-level:
npx skills add AGCO-Global/org-skills --skill aem-testing -g

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.

Skill contents

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

@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.

References

Deeper material the agent loads only when needed.