Supertest · เริ่มต้นกับ Supertest

Todo API Contract

กำหนด resource, endpoint และ response contract ที่จะใช้เป็น domain กลางของ track

HTTP contract คือข้อตกลงระหว่าง client กับ API

HTTP contract คือข้อตกลงสาธารณะว่า client จะส่ง request แบบใด และ API จะตอบกลับอย่างไร ข้อตกลงนี้ประกอบด้วย method, path, input, status, headers, response body และ error shape การเขียน E2E test ที่ดีเริ่มจาก contract ก่อนเริ่มเขียน syntax ของ Supertest

ส่วนของ contract	คำถามที่ต้องตอบ	ตัวอย่าง Todo API
Method	กำลังอ่าน สร้าง แก้ หรือ ลบอะไร	POST
Path	resource อยู่ที่ URL ใด	`/todos`
Input	ส่งข้อมูลผ่าน path/query/body/header อย่างไร	`{ title: string }`
Status	สำเร็จหรือผิดพลาดด้วยรหัสใด	201, 400, 404
Headers	client ต้องอ่าน metadata ใด	`content-type`
Body	ข้อมูลที่ caller ใช้งานได้มี shape ใด	`{ id, title, completed }`

Todo endpoint contractTEXT

นี่คือ contract กลางที่ใช้เป็น domain เดียวกันตลอด track เพื่อให้ผู้เรียนโฟกัสที่ Supertest

POST   /todos       201  { id, title, description?, completed }
GET    /todos       200  { items: Todo[], total: number }
GET    /todos/:id   200  Todo
PUT    /todos/:id   200  Todo
PATCH  /todos/:id   200  Todo
DELETE /todos/:id   200  { success: true }

contract กลางไม่ใช่กฎของทุก API

path และ status ในตัวอย่างเป็นข้อตกลงของ Todo API ในบทเรียน ให้ปรับ test ตาม contract จริงของ project ที่กำลังทำงาน อย่าเปลี่ยน expected เพียงเพื่อให้ test ผ่านโดยไม่ตรวจ API contract

อ่าน success response จาก public fields

Todo ใน track นี้มี `id`, `title`, `description` ที่เป็น optional และ `completed` เป็น boolean เมื่อสร้าง Todo สำเร็จ response ต้องเปิดเผย field ที่ client ใช้งานได้ ส่วน field ภายใน เช่น database timestamp หรือ relation ที่ไม่ได้อยู่ใน contract ไม่ควรถูก assert แบบละเอียดในทุก test

สร้าง Todo และตรวจ success contractTS

ใช้ `expect.objectContaining` เมื่อ contract สนใจเฉพาะ public fields ที่ระบุไว้ และไม่ต้องผูก test กับ field ภายในที่ไม่ได้เป็น contract

const response = await request(app.getHttpServer())
  .post("/todos")
  .send({
    title: "Ship docs",
    description: "เขียนบทเรียน Supertest",
  });

expect(response.status).toBe(201);
expect(response.body).toEqual(
  expect.objectContaining({
    id: expect.any(Number),
    title: "Ship docs",
    description: "เขียนบทเรียน Supertest",
    completed: false,
  }),
);

ตัวอย่าง success bodyJSON

`completed: false` เป็น default behavior ที่ผู้สร้าง resource และ client ควรรู้จัก

{
  "id": 1,
  "title": "Ship docs",
  "description": "เขียนบทเรียน Supertest",
  "completed": false
}

วางแผน error contract ก่อนเขียน assertion

กรณี	status ที่คาดหวัง	หลักฐานที่ควรตรวจ
สร้างสำเร็จ	201	public fields และ default state
payload ไม่ผ่าน validation	400	status และ error message/shape ตาม contract
ไม่พบ Todo	404	status และ error shape ที่ caller รู้จัก
ชื่อซ้ำหรือ conflict	409	แยก conflict ออกจาก server error
ไม่มีสิทธิ์หรือ token ใช้ไม่ได้	401/403	จะลงรายละเอียดใน phase Authentication ภายหลัง

ตัวอย่าง error responseJSON

shape จริงอาจต่างกันตาม exception filter หรือ framework configuration ให้ยึด public contract ของ project เป็นหลัก

// 400: input ไม่ผ่าน contract
{
  "statusCode": 400,
  "message": ["title must be a string"]
}

// 404: resource ไม่มีอยู่
{
  "statusCode": 404,
  "message": "Todo not found"
}

อย่า assert error ด้วยข้อความที่ละเอียดเกินความจำเป็นถ้า contract ไม่ได้สัญญาข้อความนั้น เพราะการเปลี่ยน wording เล็กน้อยไม่ควรทำให้ test ของ behavior ที่ยังถูกต้องพัง ให้ตรวจเฉพาะ status และ field ที่ caller ใช้งานจริง

แปลง contract เป็น test intent

Test intent คือประโยคสั้น ๆ ที่บอก behavior ที่ต้องการพิสูจน์ ก่อนเขียน `.post()`, `.send()` หรือ `expect()` ให้เขียนประโยคที่มีเงื่อนไข การกระทำ และผลลัพธ์ วิธีนี้ช่วยให้เลือก assertion ได้จาก contract แทนการเขียนตาม syntax ที่จำได้

intent → request → assertionTS

อ่าน test จาก intent ก่อน แล้วจึงจับคู่แต่ละส่วนกับ method, input, status และ response field

// intent:
          // เมื่อส่ง POST /todos ด้วย title ที่ถูกต้อง
          // ระบบคืน 201 และตั้ง completed เป็น false

it("creates a todo with the default completion state", async () => {
  const response = await request(app.getHttpServer())
    .post("/todos")
    .send({ title: "Ship docs" });

  expect(response.status).toBe(201);
  expect(response.body.completed).toBe(false);
});

กฎสำคัญ

request

method และ path ต้องมาจาก contract

`POST /todos` กับ `GET /todos` เป็นคนละ behavior แม้ใช้ resource เดียวกัน

status

ตรวจ status ก่อนรายละเอียด

status ช่วยบอกผลระดับ protocol ก่อนที่เราจะอ่าน body ต่อ

stable

assert public fields ที่จำเป็น

test ควรทนต่อ refactor ภายใน แต่ต้อง fail เมื่อ contract ที่ caller พึ่งพาถูกเปลี่ยน

HTTP contract คือข้อตกลงระหว่าง client กับ API

ส่วนของ contract	คำถามที่ต้องตอบ	ตัวอย่าง Todo API
Method	กำลังอ่าน สร้าง แก้ หรือ ลบอะไร	POST
Path	resource อยู่ที่ URL ใด	`/todos`
Input	ส่งข้อมูลผ่าน path/query/body/header อย่างไร	`{ title: string }`
Status	สำเร็จหรือผิดพลาดด้วยรหัสใด	201, 400, 404
Headers	client ต้องอ่าน metadata ใด	`content-type`
Body	ข้อมูลที่ caller ใช้งานได้มี shape ใด	`{ id, title, completed }`

Todo endpoint contractTEXT

POST   /todos       201  { id, title, description?, completed }
GET    /todos       200  { items: Todo[], total: number }
GET    /todos/:id   200  Todo
PUT    /todos/:id   200  Todo
PATCH  /todos/:id   200  Todo
DELETE /todos/:id   200  { success: true }

contract กลางไม่ใช่กฎของทุก API

อ่าน success response จาก public fields

สร้าง Todo และตรวจ success contractTS

const response = await request(app.getHttpServer())
  .post("/todos")
  .send({
    title: "Ship docs",
    description: "เขียนบทเรียน Supertest",
  });

expect(response.status).toBe(201);
expect(response.body).toEqual(
  expect.objectContaining({
    id: expect.any(Number),
    title: "Ship docs",
    description: "เขียนบทเรียน Supertest",
    completed: false,
  }),
);

ตัวอย่าง success bodyJSON

`completed: false` เป็น default behavior ที่ผู้สร้าง resource และ client ควรรู้จัก

{
  "id": 1,
  "title": "Ship docs",
  "description": "เขียนบทเรียน Supertest",
  "completed": false
}

วางแผน error contract ก่อนเขียน assertion

กรณี	status ที่คาดหวัง	หลักฐานที่ควรตรวจ
สร้างสำเร็จ	201	public fields และ default state
payload ไม่ผ่าน validation	400	status และ error message/shape ตาม contract
ไม่พบ Todo	404	status และ error shape ที่ caller รู้จัก
ชื่อซ้ำหรือ conflict	409	แยก conflict ออกจาก server error
ไม่มีสิทธิ์หรือ token ใช้ไม่ได้	401/403	จะลงรายละเอียดใน phase Authentication ภายหลัง

ตัวอย่าง error responseJSON

shape จริงอาจต่างกันตาม exception filter หรือ framework configuration ให้ยึด public contract ของ project เป็นหลัก

// 400: input ไม่ผ่าน contract
{
  "statusCode": 400,
  "message": ["title must be a string"]
}

// 404: resource ไม่มีอยู่
{
  "statusCode": 404,
  "message": "Todo not found"
}

แปลง contract เป็น test intent

intent → request → assertionTS

อ่าน test จาก intent ก่อน แล้วจึงจับคู่แต่ละส่วนกับ method, input, status และ response field

// intent:
          // เมื่อส่ง POST /todos ด้วย title ที่ถูกต้อง
          // ระบบคืน 201 และตั้ง completed เป็น false

it("creates a todo with the default completion state", async () => {
  const response = await request(app.getHttpServer())
    .post("/todos")
    .send({ title: "Ship docs" });

  expect(response.status).toBe(201);
  expect(response.body.completed).toBe(false);
});

กฎสำคัญ

request

method และ path ต้องมาจาก contract

`POST /todos` กับ `GET /todos` เป็นคนละ behavior แม้ใช้ resource เดียวกัน

status

ตรวจ status ก่อนรายละเอียด

status ช่วยบอกผลระดับ protocol ก่อนที่เราจะอ่าน body ต่อ

stable

assert public fields ที่จำเป็น

test ควรทนต่อ refactor ภายใน แต่ต้อง fail เมื่อ contract ที่ caller พึ่งพาถูกเปลี่ยน

HTTP contract คือข้อตกลงระหว่าง client กับ API

อ่าน success response จาก public fields

วางแผน error contract ก่อนเขียน assertion

แปลง contract เป็น test intent

กฎสำคัญ

method และ path ต้องมาจาก contract

ตรวจ status ก่อนรายละเอียด

assert public fields ที่จำเป็น

กำลังโหลดบทเรียน...

HTTP contract คือข้อตกลงระหว่าง client กับ API

อ่าน success response จาก public fields

วางแผน error contract ก่อนเขียน assertion

แปลง contract เป็น test intent

กฎสำคัญ

method และ path ต้องมาจาก contract

ตรวจ status ก่อนรายละเอียด

assert public fields ที่จำเป็น