[Rspec] 좋은 설명문 작성하기

RSpec은 TDD의 문서화에 중점을 두고 개발된 훌륭한 BDD툴입니다. (BDD는 어플리케이션의 개발과정을 확인하는 사람이 읽을 수 있는 명세서를 적는 일을 말합니다.) 저의 경우 Better Specs을 통해 좋은 테스트 스위트에 대해 알 수 있었지만 좋은 설명문에 관해서는 한가지 오해가 있었습니다. 이 글에서는 올바른 설명문에 관해 제가 했던 오해와 결론에 대해 간단히 공유하려고 합니다.

Rspec에 관한 좋은 테스트 스위트를 제시하고 있는 Better Specs에는 아래와 같은 글이 있습니다.

테스트를 설명할때 should를 사용하지 마세요. 현제 시제의 3인칭 시점으로 작성합시다. 새로나온 expectation 를 사용하시면 더욱 좋습니다.

처음 읽었을때는 it블록 안에 should대신 expect를 사용해야 한다는 식으로 오해하고 말았습니다. 그런데 다시 한번 읽어 보니 "현제 시제의 3인칭 시점으로 작성합시다."라는 문장이 눈에 띄었습니다. 그동안 제가 잘못된 이해로 작성하곤 했던 Example은 아래와 같습니다.

describe 'User' do
  describe '#updata_orders' do
    it '주문정보가 갱신됩니다' do
      ...
    end
  end
end

"주문정보가 갱신됩니다"는 그 자체로는 어색함이 없는 문장입니다. 그러나 문장 앞에 it이 있다는 사실을 생각해 보면 어색함이 느껴집니다. "주문정보가 갱신됩니다"를 it과 함께 표현하면 아래와 같은 문장이 됩니다.

그것은 주문정보가 갱신됩니다

올바른 문장은 "그것은 주문정보를 갱신합니다"이지 않을까요? 처음으로 돌아가서 "현제 시제의 3인칭 시점으로 작성합시다."에 따라 다시 작성한 Example은 아래와 같습니다.

describe 'User' do
  describe '#updata_orders' do
    it '주문정보를 갱신합니다' do
      ...
    end
  end
end

조금 더 자연스럽게 느껴지시나요? 별 차이가 없는 것 같나요? 사실 Example을 현제 시제의 3인칭 시점으로 작성으로 작성해야 하는 이유는 문법에 맞는 문장을 작성하기 위함만은 아닙니다. 더 중요한 이유는 읽기 쉬운 문서화에 있습니다.

Rspec을 통한 사람이 읽기 쉬운 문서화를 위해서는 describe와 it을 다음과 같이 정의하여야 합니다.

• describe: 설명하려고 하는 주체를 정의해야 하합니다. describe은 example group의 주어가 됩니다.
• it: it은 describe을 주어로 하는 설명문이야 합니다. 해당 문장의 it을 example group의 describe으로 교체해도 문장이 어색해지지 않아야 합니다.
  • X) 주문정보가 갱신됩니다. -> User#updata_orders는 주문정보가 갱신됩니다.
  • O) 주문정보를 갱신합니다. -> User#updata_orders는 주문정보를 갱신합니다.

위에서 예로 제시한 "잘못된 이해로 작성하곤 했던 Example"에서 "주문정보가 갱신됩니다"는 describe에서 제시된 "User#updata_orders"가 아닌 "Oder(주문정보)"를 주어로 설명해 버렸습니다. 별거 아닌 거 같고 저 정도야 어떻게 쓰든 금방 이해할 수 있을 듯하지만, 저런 잘못된 설명문 하나하나가 모여 문서화된 TDD를 읽기 어렵게 만드는 건 아닐까요?

지금까지 살펴본 Rspec에서의 좋은 설명문에 대해 요약하자면 다음과 같습니다.

• it은 describe의 대상을 가리키는 대명사입니다.
• it에 들어가는 문장은 주어가 3인칭 단수인 현재시제의 문장을 사용해야 합니다.
• it에 들어가는 문장이 describe를 가리키기 어렵다면 다른 describe가 필요한지 고민해 볼 필요가 있습니다.
• it에 들어가는 문장은 영어로 작성하기를 권합니다. 그 이유는 영어로 작성하는 편이 it이 문장의 일부라는 사실을 의식하기 쉽기 때문입니다.