---
# (DD31) Business Logic — ClinicServiceTests.shouldInsertOwner() [18 LOC]

| Field | Value |
|-------|-------|
| Fully Qualified Name | `org.springframework.samples.petclinic.service.ClinicServiceTests` |
| Layer | Test |
| Module | `service` (Package: `org.springframework.samples.petclinic.service`) |

## 1. Role

### ClinicServiceTests.shouldInsertOwner()

This test method verifies the end-to-end persistence behavior for creating a new owner record in the PetClinic owner repository. It first establishes a baseline count of owners whose last name starts with `Schultz`, then inserts a new `Owner` entity with a full set of identifying contact details, and finally confirms that the inserted record is assigned a database identifier and increases the matching owner count by exactly one.

From a business perspective, the method validates the core owner-registration pathway: a person can be captured as a new pet owner with personal and contact data, stored successfully, and immediately retrieved by the same business search rule used before insertion. The method follows a straightforward create-and-verify pattern typical of persistence tests, combining setup, command execution, and post-condition assertion in a single transactional test. There are no conditional business branches in the method; the only flow variations are the two repository read operations that bracket the insert operation. The test’s role in the larger system is to protect the integrity of the owner onboarding workflow and ensure that repository behavior remains stable for downstream screens and services that depend on owner search and save semantics.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
START["shouldInsertOwner()"]
READ1["Query owners by last name prefix \"Schultz\""]
COUNT1["Store current owner count"]
CREATE1["Instantiate new Owner"]
SET1["Set firstName = \"Sam\""]
SET2["Set lastName = \"Schultz\""]
SET3["Set address = \"4, Evans Street\""]
SET4["Set city = \"Wollongong\""]
SET5["Set telephone = \"4444444444\""]
SAVE1["owners.save(owner)"]
CHECK1["owner.getId() is not zero"]
READ2["Re-query owners by last name prefix \"Schultz\""]
ASSERT1["Assert total count increased by 1"]
END_NODE["Return"]
START --> READ1
READ1 --> COUNT1
COUNT1 --> CREATE1
CREATE1 --> SET1
SET1 --> SET2
SET2 --> SET3
SET3 --> SET4
SET4 --> SET5
SET5 --> SAVE1
SAVE1 --> CHECK1
CHECK1 --> READ2
READ2 --> ASSERT1
ASSERT1 --> END_NODE
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| - | (none) | - | - |

**External state read by the method:** `this.owners` repository bean and `pageable` test fixture state.

## 4. CRUD Operations / Called Services

### Pre-computed evidence from code analysis graph:

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `OwnerRepository.findByLastNameStartingWith` | OwnerRepository | Owner | Calls `findByLastNameStartingWith` in `OwnerRepository` |
| C | `OwnerRepository.save` | OwnerRepository | Owner | Persists a new `Owner` record and assigns its identifier |

Analyze all method calls within this method and classify each as a CRUD operation.

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `findByLastNameStartingWith(String, Pageable)` | OwnerRepository | Owner | Reads owners whose last name begins with `Schultz` to establish and verify the record count |
| C | `save(Owner)` | OwnerRepository | Owner | Creates and stores a new owner record in the persistence layer |

## 5. Dependency Trace

Trace who calls this method and what this method ultimately calls.

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | Test class entry point | `ClinicServiceTests.shouldInsertOwner()` | `findByLastNameStartingWith [R] Owner` |
| 2 | Test class entry point | `ClinicServiceTests.shouldInsertOwner()` | `save [C] Owner` |

## 6. Per-Branch Detail Blocks

**Block 1** — [SEQUENCE] `(method body)` (L107-L124)

> Transactional test flow that measures the number of matching owners, inserts a new owner, and confirms the repository count increases.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `this.owners.findByLastNameStartingWith("Schultz", pageable);` // Reads baseline matching owners |
| 2 | SET | `int found = (int) owners.getTotalElements();` // Stores the baseline count |
| 3 | SET | `Owner owner = new Owner();` // Creates a new owner instance |
| 4 | EXEC | `owner.setFirstName("Sam");` // Sets owner first name |
| 5 | EXEC | `owner.setLastName("Schultz");` // Sets owner last name used for matching search |
| 6 | EXEC | `owner.setAddress("4, Evans Street");` // Sets street address |
| 7 | EXEC | `owner.setCity("Wollongong");` // Sets city |
| 8 | EXEC | `owner.setTelephone("4444444444");` // Sets telephone number |
| 9 | CALL | `this.owners.save(owner);` // Persists the new owner record |
| 10 | EXEC | `assertThat(owner.getId()).isNotZero();` // Verifies persistence assigned an identifier |
| 11 | SET | `owners = this.owners.findByLastNameStartingWith("Schultz", pageable);` // Refreshes the matching owner list |
| 12 | EXEC | `assertThat(owners.getTotalElements()).isEqualTo(found + 1);` // Verifies the count increased by one |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `Owner` | Domain entity | Pet owner master record containing personal and contact details |
| `firstName` | Field | Owner given name used for identification and display |
| `lastName` | Field | Owner family name used for lookup and search matching |
| `address` | Field | Owner street address for contact and correspondence |
| `city` | Field | Owner city of residence |
| `telephone` | Field | Owner contact phone number |
| `findByLastNameStartingWith` | Repository method | Search operation that returns owners whose last name matches the specified prefix |
| `save` | Repository method | Persistence operation that inserts or updates an owner entity |
| `pageable` | Test fixture / query parameter | Paging request used to limit and structure repository results |
| `transactional` | Technical annotation | Ensures the test runs within a transaction and rolls back after execution |
| `Schultz` | Test data value | Sample last name used to identify the owner subset under test |
| `Sam` | Test data value | Sample first name for the inserted owner |
| `Wollongong` | Test data value | Sample city used for the inserted owner |
| `4, Evans Street` | Test data value | Sample postal address used for the inserted owner |
| `4444444444` | Test data value | Sample telephone number used for the inserted owner |
| CRUD | Acronym | Create, Read, Update, Delete — standard persistence operation categories |
| JPA | Acronym | Java Persistence API — object-relational persistence standard used by the repository layer |
| Repository | Technical term | Data access abstraction that reads and writes domain entities |
| PetClinic | Business term | Sample veterinary clinic domain used by the application |