# serverest: a fake storefront to point your API tests at

> ServeRest is a REST server that simulates an online store, so API tests have a real set of routes, seed data and documentation to work against, whether it is run online, through npm or as a Docker container. It is aimed at developers learning API testing and teams that want a stable dependency for integration and load tests.

**ServeRest/ServeRest** — APIs REST simulando loja virtual para servir de estudo de testes de API de forma manual ou automatizada

- Repository: https://github.com/ServeRest/ServeRest
- Website: https://serverest.dev
- Stars: 927 · Forks: 120
- Language: JavaScript
- License: not declared
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/serverest-serverest

## A simulated shop, not a mock in your test code

ServeRest is a REST server for the study of API testing, and its description says plainly what it is: APIs that simulate an online store, to serve as a study target for API testing, either manual or automated.

The design decision that makes it useful is where the fake lives. Rather than each test file mocking the endpoints it needs, there is a running server that behaves like a shop, with a full set of routes, and your tests talk to it over HTTP as if it were the real backend. That difference matters for anything above the request level. Status codes, headers, validation error bodies, pagination behaviour and authentication failures are all things you can only really learn by talking to a server that implements them.

The study areas the README lists are the checklist of what it covers. The verbs GET, POST, PUT and DELETE with data persistence, so a POST followed by a GET returns what you wrote. Load testing, which has its own section below. Authentication in the header, so the token handling is part of the surface rather than something you stub. Query strings, so filtering and paging are exercised. And JSON schema testing, so the response shapes are validated rather than assumed.

The homepage is serverest.dev, and the repository also carries a docs/ directory and an `examples` section pointing at automation examples, including a Java project using REST-Assured and JUnit.

## Three environments with the same routes and data

ServeRest is available online at serverest.dev, locally through npm, and locally through Docker, and the README makes a point that is easy to miss: all of these options have the same routes, rules, pre-registered data and documentation. Choose whichever suits you.

That equivalence is the point of the design. A test written against the local container behaves the same against the hosted instance, so a team can develop offline and still run a shared environment, and a course can hand out one URL.

The difference between them is the lifetime of the data. In the online environment the registered data is removed daily, while locally it is enough to restart ServeRest. The README recommends the local option if you need data that is not altered by another user, which is the honest caveat: the hosted instance is shared, and anything you create there can be modified or removed by someone else running tests at the same time.

The online instance is also described as having constant monitoring of status and uptime to guarantee it is always available, which is a reasonable answer to the obvious objection that a public sandbox disappears at the worst moment.

For automation, the local route is the one to use, and the README is unusually firm about it. Load testing must be run only in a local environment, available through npm or Docker and reachable at http://localhost:3000. The stated reason is that ignoring this would harm the open source and free project and would affect other people's study.

## Starting it locally with npx or Docker

The npm route is a single command, and it needs nothing installed locally beyond Node:

```sh
npx serverest@latest
```

The available configuration options are listed by the same tool:

```sh
npx serverest -h
```

The Docker route is equally short:

```sh
docker run -p 3000:3000 paulogoncalvesbh/serverest:latest
```

and its help output is available the same way:

```sh
docker run -p 3000:3000 paulogoncalvesbh/serverest:latest --help
```

Note the port mapping. The container exposes 3000 and the mapping publishes it on the host, which matches the http://localhost:3000 address the README uses for the local status page and the load test section.

Both commands start the latest available version, and pinning is a matter of substituting `latest` with the version you want. The available versions are listed in the Docker Hub tags and in the npm version list, and the README links both.

For a repeatable local environment, the repository also ships a docker-compose.yml with a development service that builds from the root Dockerfile, sets `FORCE_RELEASE_BANNER=true`, runs `npm run dev` as its entrypoint, mounts the working tree into the container and publishes port 3000. The Dockerfile itself is a production image based on `node:22-alpine3.20` with a pinned digest, installing production dependencies with `npm ci --production --ignore-scripts`, setting `ENVIRONMENT='docker'` and `TERM=xterm-256color`, exposing port 3000 and starting with `npm start`.

## The security headers are part of what you test

By default ServeRest changes the headers it sends, and the README explains why that is useful rather than a surprise.

By default the server adds these headers, and the behaviour can be disabled with `npx serverest --nosec`:

```text
Strict-Transport-Security: max-age=15552000; includeSubDomains
X-Content-Type-Options: nosniff
X-DNS-Prefetch-Control: off
X-Download-Options: noopen
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
```

It also removes one header:

```text
X-Powered-By: Express
```

The README tells you to use that behaviour in your tests, validating the presence or absence of those headers. That framing is what makes this a study environment rather than a toy. The question a security review asks about a header is never whether the server sets it, it is whether your application, or the gateway in front of it, still sets it once the response passes through. A test that asserts on headers is checking the thing you actually care about, and `--nosec` exists so you can test the opposite case as well.

The README points at an API security checklist for further reading on that subject.

## Load testing against localhost, and the status page

The load testing section is short and strict. The test must be executed only in a local environment, available through npm or Docker and accessible via http://localhost:3000. The reason given is that not following this harms the open source project and affects other people's study.

That instruction is the whole story about ServeRest's hosted instance. It is a shared resource for learning, and a load test against it would deny service to everyone else using it at the time. The local instance is where the traffic goes.

To watch what the server is doing under that traffic, there is a status page at http://localhost:3000/status, and it is available only locally. It reports CPU usage, memory usage, response time and RPS, requests per second.

That status page is what turns load testing from guesswork into measurement. Whether a particular endpoint or payload shape is the bottleneck is a question about response time and throughput under a specific request profile, and those two numbers are what the page gives you. The README also asks, somewhat pointedly, that if you have run a load test, you share the repository and the final report with RPS data so the project can understand the behaviour of its infrastructure.

Note the scope, though. The status page reports the server's own CPU and memory, so it tells you whether the process is saturated. It does not break the request down by endpoint or by payload, so diagnosing which of your calls is slow is still on you.

## The test tooling the project runs on itself

The package.json shows how thoroughly the project tests itself, and that is worth knowing because the same scripts are available to anyone who forks it.

Unit tests run under `nyc` with mocha, with the coverage report written to `./coverage-unit` and coverage checking disabled for that run. Integration tests use the same shape with `./coverage-integration`. End to end tests run the integration configuration with `--fgrep @skipE2E --invert`, and smoke tests run with `--grep @smokeE2E`. Contract tests run `mocha test/contract --timeout 60000` and, from the compose file, expect `PACT_BROKER_TOKEN` and `PACT_URL` in the environment, which means the contract suite talks to a Pact broker.

There is also mutation testing through Stryker, with `test:mutation` and a `test:mutation:diff` variant that diffs against the trunk branch, and a `merge-lcov` script that combines the coverage files with `lcov-result-merger`.

Two smaller details say something about the project's habits. Linting uses `standard`, the opinionated JavaScript style, with staged linting through lint-staged and husky hooks configured in the `prepare` script. And there is an `i18n:validate` script that runs `scripts/i18n-validate.js`, which exists because the online instance serves localised documentation.

The docker-compose file wires these suites together as services with shared bases, and it also carries Datadog CI visibility environment variables, `DD_CIVISIBILITY_AGENTLESS_ENABLED`, `DD_API_KEY`, `DD_SITE` and the git metadata, so the test runs report into their CI tooling.

## GPL-3.0 terms, trunk branch, and an open source dependency

The licence question needs a note. The repository licence metadata is listed as unknown, while the package.json declares `"license": "GPL-3.0"`, with the package published to npm under that declaration. The README does not carry a licence section of its own in the excerpt above, so the package metadata is the clearest statement, and if you intend to vendor the code rather than run the published package, read the LICENSE file in the repository before you do.

GPL-3.0 matters here more than it would for a library you import. ServeRest is something you run, typically as a container in CI, so the question of how you distribute it and whether you modify it is a real question for a commercial engineering organisation. Running the published npm or Docker artefact as a test dependency is a different situation from shipping a modified copy inside your own product, and the answer to that distinction is for your legal team rather than for this article.

The project is funded through Open Collective, according to the funding block in package.json, which is the usual arrangement for a free community resource that needs to pay for hosting. The README also offers a badge for repositories that use ServeRest, with the markdown snippet to paste at the top of your README.

On maintenance, the default branch is `trunk` rather than `main`, and the release history shows v3.2.0 on 2026-02-10, v3.2.1 on 2026-07-31 and v3.2.2 on 2026-08-26, with the last push on the same day as v3.2.2. Releases are automated through a `.releaserc.js` configuration with commitlint and conventional commits behind them.

For an adopter, the practical summary is that you are taking a dependency on a community-run service with a permissive-looking but copyleft licence, a monthly-ish release rhythm, and a hosted instance whose data is wiped daily. Running it locally with a pinned version removes the last of those concerns.

## Conclusion

Adopt serverest when you want API tests that exercise a realistic REST surface, with CRUD endpoints, authentication in the header, query strings and JSON schema validation already in place, and you want the same behaviour online, through npm or through Docker. Skip it if your tests need a domain your product owns, since the store is a fixed fixture, or if you need load testing against anything but a local instance. Verify first that the pre-registered data matches what your tests assume, and that your local instance resets the way you expect between runs, since the online environment clears its data daily. The package.json declares GPL-3.0, the last push was on 2026-08-26, and the current release is v3.2.2.

## FAQ

### What is ServeRest and what can I test with it?

ServeRest is a REST server that simulates an online store so you can study API testing manually or automatically. It covers the GET, POST, PUT and DELETE verbs with data persistence, load testing, authentication in the header, query strings and JSON schema testing.

### How do I run ServeRest locally?

With npm the command is `npx serverest@latest`, and with Docker it is `docker run -p 3000:3000 paulogoncalvesbh/serverest:latest`. Both publish port 3000, and both accept `--help` or `-h` to list the available configuration options.

### Do the online and local ServeRest environments behave differently?

The README states that all options have the same routes, rules, pre-registered data and documentation. The difference is data lifetime: in the online environment the registered data is removed daily, while locally it is enough to restart ServeRest, which is why the README suggests the local option if you need data that other users cannot alter.

### Can I run load tests against the hosted ServeRest?

No. The README states that the load test must be run only in a local environment available through npm or Docker and reachable at http://localhost:3000, because not following that harms the open source project and affects other people's study.

### How do I see what ServeRest is doing under load?

The status page at http://localhost:3000/status is available only locally and contains CPU usage, memory usage, response time and RPS. The README also asks that you share the repository and the final report with RPS data after a load test.

### What licence does ServeRest use?

The repository licence metadata is listed as unknown, while the package.json declares GPL-3.0 for the npm package. The package version is 3.2.2, released on 2026-08-26, and the project is funded through Open Collective.

## Sources

- [Issues](https://github.com/ServeRest/ServeRest/issues)
- [Project website](https://serverest.dev)
- [README](https://github.com/ServeRest/ServeRest/blob/trunk/README.md)
- [Releases](https://github.com/ServeRest/ServeRest/releases)
- [ServeRest/ServeRest on GitHub](https://github.com/ServeRest/ServeRest)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/serverest-serverest