Functions, Custom Properties, Reusable Fragments, and Modular Plans: Configuration, Design Patterns, and Trade-Offs

1. Mandatory path stays local/free

2. Function versus variable versus property

3. Module Controller versus Include Controller

Start with Module when reuse is local to one plan. Move to Include when independent reuse justifies the extra file/path/dependency contract.

4. One JMX versus several modules

One JMX has fewer deployment/path problems and is easier for a beginner to trace. It becomes awkward when many scenarios duplicate a stable flow or teams need separate ownership/release cadence.

Several JMX modules reduce definition duplication and permit targeted ownership, but require dependency naming, file deployment, path resolution, and compatibility/version policy. Keep the module graph shallow and acyclic.

5. Relative paths versus explicit project-root resolution

The Chapter 20 mandatory solution uses an explicit launcher-derived absolute includecontroller.prefix. The JMX keeps only the stable filename session-bootstrap.jmx.

6. Property files versus command-line run overrides

Use a committed synthetic environment property file for stable defaults such as localhost host/port and conservative load ceilings. Use explicit -J values for run identity/variant or intentional one-off overrides.

Do not place real credentials in either. JMeter property files and command manifests are ordinary files and can be committed/artifacted accidentally.

7. Explicit defaults versus fail-fast configuration

An explicit safe default makes a lab runnable. Production/release plans sometimes need a stricter contract where a missing property should fail before traffic. Since __P can silently return 1 when no default is supplied, use one of these patterns:

• always specify an explicit conservative default and record resolved values;
• use a one-time preflight assertion/script to reject missing/unsafe properties before Thread Groups start;
• have the launcher validate required keys before invoking JMeter.

8. Generated data versus committed synthetic fixtures

Committed small synthetic fixtures are easy to review and reproduce. Generated data is useful when the dataset is large or must vary structurally, but the generator/version/seed/manifest becomes part of evidence.

For exact replay, prefer deterministic generation or a committed/generated manifest rather than unseeded random functions.

9. Randomness needs a reproducibility strategy

__Random(min,max) returns a pseudo-random number but exposes no seed parameter. If exact numeric sequence matters, the current Random Variable Config Element offers a Random Seed and Per Thread option. Alternatively, pre-generate a seeded CSV dataset outside load execution.

__UUID() is excellent for unique correlation when exact replay is not required; do not confuse uniqueness with reproducibility.

10. Keep function use readable

Prefer:

Property-backed defaults:
HOST = ${__P(target.host,127.0.0.1)}
PORT = ${__P(target.port,8020)}
RUN_ID = ${__P(run.id,p20-local)}

Sampler:
user=user-${__threadNum}
run_id=${__P(run.id,p20-local)}

over a single field containing nested conditionals, random values, time functions, properties and string concatenation. If a reviewer cannot predict the effective request without executing the expression, the plan is too opaque.

11. Fragment input/output contract

FRAG.session.bootstrap.v1 owns:

• input: target defaults already available from top-level plan; run.id/variant properties; current __threadNum;
• action: one POST session-create request;
• output: thread-local SESSION_ID;
• assertion: status created and SESSION_ID exists;
• does not own: thread count, pacing, Cookie Manager, run result files, cleanup, or global mutable properties.

This contract keeps the fragment reusable without hiding workload control.

12. Configuration-layer boundaries

13. Distributed-run implication

Remote engines do not share the controller's filesystem. External fragments, property files, and data required by a remote plan must exist consistently on every engine, and JVM-global properties are global only within each engine. Chapter 20 does not run RMI; it teaches the dependency contract now so Chapter 25 can apply it safely.

14. Worked scenario

Four top-level plans share a 6-step authentication bootstrap, but only two use the same cookie/config assumptions.

• Do not make one giant fragment controlled by many Boolean properties.
• Create a stable common bootstrap module only if its inputs/outputs truly match.
• Keep top-level Cookie Manager/UDVs/environment config in each main plan.
• Use Include for cross-plan reuse, unique names, explicit prefix/deployment policy.
• Keep plan-specific assertions/branch logic near the callers.

15. Decision table

16. Configured versus achieved load

Configured workload is resolved thread/loop/pacing properties plus runtime controller placement. Achieved workload is the successful session-create/work/delete sample count and target event distribution. A modular refactor is performance-valid only when generator path/module resolution succeeds and the target workload remains equivalent. Preserve JTL + matching jmeter.log, properties, command manifest, fragment graph, resolved prefix, generator CPU/heap, target events, and duplication note.

Knowledge check

Official references and version notes

• JMeter Component Reference — Module Controller — runtime substitution of an already loaded controller/fragment and unique fragment naming.
• JMeter Component Reference — Include Controller — external JMX/Test Fragment use, filename limitations, includecontroller.prefix, and path fallback behavior.
• JMeter Component Reference — Test Fragment — reusable fragment semantics with Module/Include Controllers.
• JMeter Functions — __P — simplified command-line property lookup and default behavior.
• JMeter Functions — __property — general JMeter property lookup and optional variable assignment.
• JMeter Functions — __threadNum — thread-group-local thread numbering and Configuration Element restrictions.
• JMeter Functions — __Random — pseudo-random values and optional variable assignment.
• JMeter Component Reference — Random Variable — seeded/per-thread reproducible random-number option.
• JMeter Getting Started — -q/-J, property files, and JMeter configuration loading.
• JMeter Best Practices — GUI authoring/debugging and non-GUI execution for load.
• Apache JMeter downloads — current stable release and Java requirement.