🧱 Jest 개념 정리 - Expect / Matcher / Modifier

공식 문서: https://jestjs.io/docs/expect#reference

---

🎯 1. Expect

💡 개념

expect()는 테스트할 실제 값(actual) 을 감싸는 함수다.
이 함수는 내부적으로 Expectation 객체를 반환한다.
이 객체에는 여러 매처(Matcher) 메서드와 수정자(Modifier) 속성이 포함되어 있다.

---

🧩 2. Matcher

💡 개념

Matcher는 expect()가 반환한 Expectation 객체의 메서드로,
실제 값(actual)과 기대 값(expected)을 비교(Assertion)한다.

expect(2 + 2).toBe(4);

• expect(2 + 2) → 실제 값(4)을 감싼 Expectation 객체
• .toBe(4) → Matcher 메서드, 실제 값과 기대값 비교 수행

조건이 맞지 않으면 Jest가 테스트를 실패로 처리한다.

---

🧠 3. Modifier

💡 개념

Modifier(수정자) 는 매처의 동작을 바꾸는 보조 속성이다.
매처를 호출하기 전에 체인으로 붙여서 실행 결과를 수정한다.

Modifier	설명	예시
.not	매처 결과를 반대로 뒤집음	expect(3 + 2).not.toBe(6)
.resolves	Promise가 resolve될 때 결과 검증	await expect(Promise.resolve('ok')).resolves.toBe('ok')
.rejects	Promise가 reject될 때 에러 검증	await expect(Promise.reject(new Error('fail'))).rejects.toThrow('fail')

---

🧩 4. 전체 구조 요약

expect(value)
   ↓
Expectation 객체
   ├── .toBe()        → Matcher
   ├── .toEqual()     → Matcher
   ├── .toContain()   → Matcher
   ├── .not           → Modifier
   ├── .resolves      → Modifier
   └── .rejects       → Modifier

---

⚙️ 5. 내부 구조 이해하기 (학습용 예시)

아래 예시는 Jest의 실제 구조를 단순화한 개념적 모델이다.
내부적으로는 훨씬 복잡하지만, 전체 흐름은 아래 코드처럼 동작한다 👇

function expect(actualValue) {
  return {
    // ✅ 매처들
    toBe(expected) {
      if (actualValue !== expected) {
        throw new Error(`❌ Expected ${actualValue} to be ${expected}`);
      }
    },

    toEqual(expected) {
      const isEqual = JSON.stringify(actualValue) === JSON.stringify(expected);
      if (!isEqual) {
        throw new Error(
          `❌ Expected ${JSON.stringify(actualValue)} to equal ${JSON.stringify(
            expected
          )}`
        );
      }
    },

    toContain(expected) {
      if (!actualValue.includes || !actualValue.includes(expected)) {
        throw new Error(`❌ Expected ${actualValue} to contain ${expected}`);
      }
    },

    // 🚫 부정 Modifier
    not: {
      toBe(expected) {
        if (actualValue === expected) {
          throw new Error(`❌ Expected ${actualValue} not to be ${expected}`);
        }
      },
      toContain(expected) {
        if (actualValue.includes && actualValue.includes(expected)) {
          throw new Error(
            `❌ Expected ${actualValue} not to contain ${expected}`
          );
        }
      },
    },

    // 🔄 비동기 Modifier
    resolves: {
      async toBe(expected) {
        const resolved = await actualValue;
        if (resolved !== expected) {
          throw new Error(
            `❌ Expected Promise to resolve to ${expected}, but got ${resolved}`
          );
        }
      },
    },

    rejects: {
      async toThrow(expectedMessage) {
        try {
          await actualValue;
          throw new Error(
            `❌ Expected Promise to reject, but it resolved successfully`
          );
        } catch (error) {
          if (!error.message.includes(expectedMessage)) {
            throw new Error(
              `❌ Expected rejection message to include "${expectedMessage}", but got "${error.message}"`
            );
          }
        }
      },
    },
  };
}

이 예시를 보면 다음 흐름이 자연스럽게 보인다 👇

• expect() → Expectation 객체 생성
• .toBe(), .toEqual(), .toContain() → Matcher 메서드들
• .not, .resolves, .rejects → Modifier 속성들

---

✅ 6. 핵심 정리 표

개념	역할	형태	내부 동작
Expect	테스트할 값을 감싸고 Expectation 객체 반환	함수	return new Expectation(actual)
Matcher	실제 값 vs 기대 값 비교	메서드	실패 시 throw Error
Modifier	매처 동작 변경 (not / resolves / rejects)	프로퍼티	내부 플래그나 체인 구조로 매처의 결과 수정

---

🧭 7. 한 문장 요약

Jest의 테스트 구조는
expect() → (modifier) → matcher
형태의 체인형 검증(Assertion Chain) 으로 구성된다.

---