supertest

KO | EN

gitlite — search

#hacktoberfest #ai #android #rust #macos #nodejs #windows #awesome #cli #kubernetes #security #ios #openai #mcp

(★ 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

// 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

supertest

파일 탐색기

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

supertest

파일 탐색기

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README