supertest - GitLite

KO | EN

gitlite — search

#python #hacktoberfest #ai #go #golang #rust #linux #nodejs #macos #kubernetes #awesome-list #security #mcp #openai

supertest

(★ 14,395)

🕷 유창한 API를 사용하여 Node.js HTTP 서버를 테스트하기 위한 슈퍼 에이전트 기반 라이브러리입니다. @forwardemail, @ladjs, @spamscanner, @breejs, @cabinjs, @lassjs를 위해 유지 관리됩니다.

파일 탐색기

최종 버전 다운로드 (.zip)

- - ci.yml
- remove-deps-4-old-node.js
- - assertion.js
  - index.js
- agent.js
- test.js
- - test_cert.pem
  - test_key.pem
- .eslintrc
- cookies.js
- issue-fixes.js
- supertest.js
- throwError.js
.commitlintrc.js
.editorconfig
.eslintrc
.gitignore
.npmignore
.npmrc
index.js
LICENSE
package-lock.json
package.json
README.md

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/forwardemail/supertest

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd supertest

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. Node.js

쉬움 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Node.js npm 명령어를 쓰려면 Node.js가 설치되어 있어야 합니다. LTS(장기지원) 버전을 추천합니다.

npm install supertest --save-dev

package.json에 명시된 라이브러리들을 내려받아 설치합니다.

✅ 명령어 실행 후 터미널에 나타나는 주소(보통 http://localhost:3000 형태)를 브라우저에서 열어보세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# [supertest](https://forwardemail.github.io/superagent/)

[![build status](https://github.com/forwardemail/supertest/actions/workflows/ci.yml/badge.svg)](https://github.com/forwardemail/supertest/actions/workflows/ci.yml)
[![code coverage](https://img.shields.io/codecov/c/github/ladjs/supertest.svg)](https://codecov.io/gh/ladjs/supertest)
[![code style](https://img.shields.io/badge/code_style-XO-5ed9c7.svg)](https://github.com/sindresorhus/xo)
[![styled with prettier](https://img.shields.io/badge/styled_with-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
[![made with lass](https://img.shields.io/badge/made_with-lass-95CC28.svg)](https://lass.js.org)
[![license](https://img.shields.io/github/license/ladjs/supertest.svg)](https://raw.githubusercontent.com/forwardemail/supertest/master/LICENSE)

> [superagent](http://github.com/ladjs/superagent)을 통해 간편하게 HTTP 단언(assertion)을 수행하세요. [Forward Email](https://github.com/forwardemail)과 [Lad](https://github.com/ladjs)에서 유지보수하고 있습니다.

## 소개

이 모듈의 개발 동기는 HTTP 테스트를 위한 고수준 추상화를 제공하는 동시에, superagent가 제공하는 [더 저수준의 API](https://forwardemail.github.io/superagent/)도 그대로 활용할 수 있도록 하는 것입니다.

## 시작하기

supertest를 npm 모듈로 설치하고 package.json 파일에 개발 의존성(development dependency)으로 저장합니다:

```bash
npm install supertest --save-dev
```

설치가 완료되면 단순히 ```require('supertest');```를 호출하여 참조할 수 있습니다.

## 예제

`request()`에 `http.Server` 또는 `Function`을 전달할 수 있습니다. 서버가 아직 연결을 수신 대기 중이 아닌 경우 임시 포트에 자동으로 바인딩되므로 포트를 직접 관리할 필요가 없습니다.

supertest는 어떤 테스트 프레임워크와도 함께 사용할 수 있습니다. 다음은 테스트 프레임워크를 전혀 사용하지 않는 예제입니다:

```js
const request = require('supertest');
const express = require('express');

const app = express();

app.get('/user', function(req, res) {
  res.status(200).json({ name: 'john' });
});

request(app)
  .get('/user')
  .expect('Content-Type', /json/)
  .expect('Content-Length', '15')
  .expect(200)
  .end(function(err, res) {
    if (err) throw err;
  });
```

http2 프로토콜을 활성화하려면 `request` 또는 `request.agent`에 옵션을 추가하기만 하면 됩니다:

```js
const request = require('supertest');
const express = require('express');

const app = express();

app.get('/user', function(req, res) {
  res.status(200).json({ name: 'john' });
});

request(app, { http2: true })
  .get('/user')
  .expect('Content-Type', /json/)
  .expect('Content-Length', '15')
  .expect(200)
  .end(function(err, res) {
    if (err) throw err;
  });

request.agent(app, { http2: true })
  .get('/user')
  .expect('Content-Type', /json/)
  .expect('Content-Length', '15')
  .expect(200)
  .end(function(err, res) {
    if (err) throw err;
  });
```

다음은 mocha를 사용한 예제입니다. `.expect()` 호출에 `done`을 바로 전달할 수 있는 것을 주목하세요:

```js
describe('GET /user', function() {
  it('responds with json', function(done) {
    request(app)
      .get('/user')
      .set('Accept', 'application/json')
      .expect('Content-Type', /json/)
      .expect(200, done);
  });
});
```

[superagent](https://forwardemail.github.io/superagent/#authentication)와 같은 방식으로 `auth` 메서드를 사용하여 HTTP 사용자 이름과 비밀번호를 전달할 수 있습니다:

```js
describe('GET /user', function() {
  it('responds with json', function(done) {
    request(app)
      .get('/user')
      .auth('username', 'password')
      .set('Accept', 'application/json')
      .expect('Content-Type', /json/)
      .expect(200, done);
  });
});
```

위 내용과 관련하여 한 가지 주목할 점은, 상태 코드 기대치(예: `.expect(302)`)를 추가하지 않은 경우 superagent는 2XX 응답 코드가 아닌 모든 HTTP 오류를 콜백의 첫 번째 인수로 전달한다는 것입니다.

`.end()` 메서드를 사용하는 경우, 실패한 `.expect()` 단언문(assertion)은 예외를 발생시키지 않으며, 대신 단언문 에러를 `.end()` 콜백으로 반환합니다. 테스트 케이스를 실패시키려면 다음과 같이 에러를 다시 발생시키거나 `err`를 `done()`에 전달해야 합니다.

```js
describe('POST /users', function() {
  it('responds with json', function(done) {
    request(app)
      .post('/users')
      .send({name: 'john'})
      .set('Accept', 'application/json')
      .expect('Content-Type', /json/)
      .expect(200)
      .end(function(err, res) {
        if (err) return done(err);
        return done();
      });
  });
});
```

Promise를 사용할 수도 있습니다:

```js
describe('GET /users', function() {
  it('responds with json', function() {
    return request(app)
      .get('/users')
      .set('Accept', 'application/json')
      .expect('Content-Type', /json/)
      .expect(200)
      .then(response => {
         expect(response.body.email).toEqual('foo@bar.com');
      })
  });
});
```

또는 async/await 문법을 사용할 수 있습니다:

```js
describe('GET /users', function() {
  it('responds with json', async function() {
    const response = await request(app)
      .get('/users')
      .set('Accept', 'application/json')
    expect(response.headers["content-type"]).toMatch(/json/);
    expect(response.status).toEqual(200);
    expect(response.body.email).toEqual('foo@bar.com');
  });
});
```

단언문은 정의된 순서대로 실행됩니다. 이 특성을 이용하면 단언문을 실행하기 전에 응답 본문(body)이나 헤더를 수정할 수 있습니다.

```js
describe('POST /user', function() {
  it('user.name should be an case-insensitive match for "john"', function(done) {
    request(app)
      .post('/user')
      .send('name=john') // x-www-form-urlencoded upload
      .set('Accept', 'application/json')
      .expect(function(res) {
        res.body.id = 'some fixed id';
        res.body.name = res.body.name.toLowerCase();
      })
      .expect(200, {
        id: 'some fixed id',
        name: 'john'
      }, done);
  });
});
```

superagent로 할 수 있는 모든 것은 supertest로도 할 수 있습니다. 예를 들어 멀티파트 파일 업로드도 가능합니다!

```js
request(app)
  .post('/')
  .field('name', 'my awesome avatar')
  .field('complex_object', '{"attribute": "value"}', {contentType: 'application/json'})
  .attach('avatar', 'test/fixtures/avatar.jpg')
  ...
```

매번 app이나 url을 전달할 필요는 없습니다. 동일한 호스트를 테스트하는 경우 초기화된 app 또는 url로 request 변수를 다시 할당하기만 하면 됩니다. `request.VERB()` 호출당 새로운 `Test`가 생성됩니다.

```js
request = request('http://localhost:5555');

request.get('/').expect(200, function(err){
  console.log(err);
});

request.get('/').expect('heya', function(err){
  console.log(err);
});
```

다음은 mocha를 사용하여 요청과 쿠키를 유지(persist)하는 방법을 보여주는 예시입니다:

```js
const request = require('supertest');
const should = require('should');
const express = require('express');
const cookieParser = require('cookie-parser');

describe('request.agent(app)', function() {
  const app = express();
  app.use(cookieParser());

app.get('/', function(req, res) {
    res.cookie('cookie', 'hey');
    res.send();
  });

app.get('/return', function(req, res) {
    if (req.cookies.cookie) res.send(req.cookies.cookie);
    else res.send(':(')
  });

const agent = request.agent(app);

it('should save cookies', function(done) {
    agent
    .get('/')
    .expect('set-cookie', 'cookie=hey; Path=/', done);
  });

it('should send cookies', function(done) {
    agent
    .get('/return')
    .expect('hey', done);
  });
});
```

[agency.js](https://github.com/ladjs/superagent/blob/master/test/node/agency.js) 파일에서 소개하는 또 다른 예시가 있습니다.

다음은 요청에 2개의 쿠키가 설정되는 예시입니다.

```js
agent(app)
  .get('/api/content')
  .set('Cookie', ['nameOne=valueOne;nameTwo=valueTwo'])
  .send()
  .expect(200)
  .end((err, res) => {
    if (err) {
      return done(err);
    }
    expect(res.text).to.be.equal('hey');
    return done();
  });
```

## API

[superagent](http://github.com/ladjs/superagent)의 메서드(`.write()`, `.pipe()` 등 포함)를 자유롭게 사용할 수 있으며, 저수준의 요구사항을 위해 `.end()` 콜백에서 단언(assertion)을 수행할 수 있습니다.

### .expect(status[, fn])

응답 `status` 코드를 단언합니다.

### .expect(status, body[, fn])

응답 `status` 코드와 `body`를 단언합니다.

### .expect(body[, fn])

문자열, 정규식 또는 파싱된 본문 객체를 사용하여 응답 `body` 텍스트를 단언합니다.

### .expect(field, value[, fn])

문자열 또는 정규식을 사용하여 헤더 `field`의 `value`를 단언합니다.

### .expect(function(res) {})

사용자 정의 단언 함수를 전달합니다. 검사할 응답 객체가 인자로 전달됩니다. 검사가 실패하면 에러를 던집니다.

```js
request(app)
  .get('/')
  .expect(hasPreviousAndNextKeys)
  .end(done);

function hasPreviousAndNextKeys(res) {
  if (!('next' in res.body)) throw new Error("missing next key");
  if (!('prev' in res.body)) throw new Error("missing prev key");
}
```

### .end(fn)

요청을 수행하고 `fn(err, res)`를 호출합니다.

## Cookies

`set` 및 `not` 쿠키 단언을 사용하는 예제입니다:

```js
// setup super-test
const request = require('supertest');
const express = require('express');
const cookies = request.cookies;

// setup express test service
const app = express();

app.get('/users', function(req, res) {
  res.cookie('alpha', 'one', { domain: 'domain.com', path: '/', httpOnly: true });
  res.send(200, { name: 'tobi' });
});

// test request to service
request(app)
  .get('/users')
  .expect('Content-Type', /json/)
  .expect('Content-Length', '15')
  .expect(200)
  // assert 'alpha' cookie is set with domain, path, and httpOnly options
  .expect(cookies.set({ name: 'alpha', options: ['domain', 'path', 'httponly'] }))
  // assert 'bravo' cookie is NOT set
  .expect(cookies.not('set', { name: 'bravo' }))
  .end(function(err, res) {
    if (err) {
      throw err;
    }
  });
```

다음과 같이 단언을 체이닝하는 것도 가능합니다:

```js
cookies.set({/* ... */}).not('set', {/* ... */})
```

### Cookie 단언

함수와 메서드는 체이닝이 가능합니다.

#### cookies([secret], [asserts])

[super-test](https://github.com/visionmedia/supertest) `.expect()` 메서드를 위한 단언 함수를 가져옵니다.

*인수*

- `secret` - 문자열 또는 문자열 배열. 쿠키 서명 비밀키.
- `asserts(req, res)` - 함수 또는 함수 배열. 실패한 사용자 정의 단언은 에러를 던져야 합니다.

#### .set(expects, [assert])

쿠키와 옵션이 설정되었음을 단언합니다.

*인수*

- `expects` - 객체 또는 객체 배열.
  - `name` - 쿠키의 문자열 이름.
  - `options` - *선택 사항* 옵션 배열.
- `assert` - *선택 사항* 부울 타입의 "참 단언" 수정자. 기본값: `true`.

#### .reset(expects, [assert])

쿠키가 설정되었고 (요청 헤더에) 이미 설정되어 있었음을 단언합니다.

*인수*

- `expects` - 객체 또는 객체 배열.
  - `name` - 쿠키의 문자열 이름.
- `assert` - *선택 사항* 부울 타입의 "참 단언" 수정자. 기본값: `true`.

#### .new(expects, [assert])

쿠키가 설정되었고 (요청 헤더에) 아직 설정되지 않았음을 단언합니다.

*인수*

- `expects` - 객체 또는 객체 배열.
  - `name` - 쿠키의 문자열 이름.
- `assert` - *선택 사항* 부울 타입의 "참 단언" 수정자. 기본값: `true`.

#### .renew(expects, [assert])

주어진 값보다 엄격하게 더 나중의 `expires` 또는 `max-age`로 쿠키가 설정되었음을 단언합니다.

*인수*

- `expects` - 객체 또는 객체 배열.
  - `name` - 쿠키의 문자열 이름.
  - `options` - 옵션 객체. `아래 두 옵션 중 하나를 사용하세요`
  - `options`.`expires` - 원본 쿠키의 UTC 만료 시간 문자열 (요청 헤더 내).
  - `options`.`max-age` - 원본 쿠키의 초 단위 ttl 정수 (요청 헤더 내).
- `assert` - *선택 사항* 부울 타입의 "참 단언" 수정자. 기본값: `true`.

#### .contain(expects, [assert])

쿠키가 값과 함께 설정되었고 옵션을 포함하고 있음을 단언합니다.

쿠키가 서명된 경우 `cookies(secret)` 초기화가 필요합니다.

*인수*

- `expects` - 객체 또는 객체 배열.
  - `name` - 쿠키의 문자열 이름.
  - `value` - *선택 사항* 쿠키의 서명되지 않은 문자열 값.
  - `options` - *선택 사항* 옵션 객체.
  - `options`.`domain` - *선택 사항* 문자열 도메인.
  - `options`.`path` - *선택 사항* 문자열 경로.
  - `options`.`expires` - *선택 사항* UTC 만료일 문자열.
  - `options`.`max-age` - *선택 사항* 초 단위의 정수 TTL.
  - `options`.`secure` - *선택 사항* 불리언 secure 플래그.
  - `options`.`httponly` - *선택 사항* 불리언 httpOnly 플래그.
- `assert` - *선택 사항* 불리언 "assert true" 수식어. 기본값: `true`.

#### .not(method, expects)

"assert true" 수식어를 `false`로 설정하여 모든 쿠키 단언(assertion) 메서드를 호출합니다.

문법 설탕(Syntactic sugar)입니다.

*인수*

- `method` - 문자열 메서드 이름. 메서드 이름의 인수는 `expects`에 적용됩니다.
- `expects` - 객체 또는 객체 배열.
  - `name` - 쿠키의 문자열 이름.
  - `value` - *선택 사항* 쿠키의 서명되지 않은 문자열 값.
  - `options` - *선택 사항* 옵션 객체.

## 참고 사항

vows 결합을 제외하고 [api-easy](https://github.com/flatiron/api-easy)에서 영감을 받았습니다.

## 라이선스

MIT

[coverage-badge]: https://img.shields.io/codecov/c/github/ladjs/supertest.svg
[coverage]: https://codecov.io/gh/ladjs/supertest
[travis-badge]: https://travis-ci.org/ladjs/supertest.svg?branch=master
[travis]: https://travis-ci.org/ladjs/supertest
[dependencies-badge]: https://david-dm.org/ladjs/supertest/status.svg
[dependencies]: https://david-dm.org/ladjs/supertest
[prs-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square
[prs]: http://makeapullrequest.com
[license-badge]: https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square
[license]: https://github.com/ladjs/supertest/blob/master/LICENSE