DeepL API mock server

A mock server that simulates some behaviour of the
DeepL API to simplify application
testing. In addition, a proxy server is included to test proxy usage.

Note: this server is intended for testing, not for use in production, and it might not receive
regular security updates.

Usage

The server listens on two ports: the main port (by default: 3000) imitates the DeepL API, and the
proxy port (by default: 3001) implements a basic proxy server.

Using Docker

With Docker, no other software needs to be installed. Build a Docker image using the provided Dockerfile:

docker image build -t deepl/deepl-mock .

Run a Docker container using the image, exposing ports 3000 and 3001:

docker run -d --rm --name deepl-mock -p3000:3000 -p3001:3001 deepl/deepl-mock

If you are executing unit tests of an official DeepL client library (for example
deepl-python
or deepl-dotnet), define the following
environment variables before executing the tests:

export DEEPL_MOCK_SERVER_PORT=3000
export DEEPL_MOCK_PROXY_SERVER_PORT=3001
export DEEPL_SERVER_URL=http://localhost:3000
export DEEPL_PROXY_URL=http://localhost:3001

# Execute tests -- see the corresponding client library documentation
...

When finished, stop the Docker container:

docker stop deepl-mock

Manually

You can also run the server manually without using Docker. First install
Node.js, then proceed using npm:

npm install     # Install required packages
npm audit       # Check for security updates
npm start       # Run the mock server

By default, the mock server listens on ports 3000 (main API) and 3001 (basic proxy). Define the
DEEPL_MOCK_SERVER_PORT and DEEPL_MOCK_PROXY_SERVER_PORT environment variables to change this
behaviour:

export DEEPL_MOCK_SERVER_PORT=4000
export DEEPL_MOCK_PROXY_SERVER_PORT=4001
npm start

If you are executing unit tests of an official DeepL client library the DEEPL_SERVER_URL and
DEEPL_PROXY_URL environment variables should also be updated.

Server configuration via HTTP-request header

The HTTP-request header mock-server-session may be sent with any request, containing a unique string identifying the
test session. A session identifier could be, for example, a test-case name and UUID.

When the server receives an unrecognized session identifier, it creates a new session and uses the session headers
(listed in the table below) to configure the session. These settings affect all requests in that session. Note that
once created, sessions cannot be reconfigured.

The server removes sessions after 10 minutes of inactivity.

Limitations compared with the DeepL API

Limited translation

The real DeepL API can accurately translate arbitrary text, however this mock server can only translate the test
phrase "proton beam" among the DeepL-supported languages, and multi-line text where each line contains the phrase
"proton beam". The translation functions will check the desired target language and respond with the corresponding
translation of "proton beam", regardless of the input text.

Additionally, this mock server cannot auto-detect the source language, unless it matches one of the test phrase
translations. Otherwise, the source language is assumed to be English.

Simplified glossaries

This mock server implements glossaries and translations using glossaries, but translations will only
make use of glossary terms if the whole input text (or each line in a document) exactly matches a
glossary term. In contrast, the real DeepL API uses sentence context and language grammar when
applying glossary terms.

User accounts

This server creates a new user account whenever it receives a request with an unrecognized auth_key. To test
behaviour due to an incorrect key use either an empty key, or the value "invalid". The server removes user accounts
after 10 minutes of inactivity.

Only .txt and .htm/.html files

This mock server only supports .txt and .htm/.html files for document translation. The DeepL API additionally supports
.docx, .pptx, .pdf, .html/.htm, .xlf/.xliff, and .xlsx files. The server removes documents after 10 minutes of inactivity.

Account usage

This mock server uses simplified calculations to update account usage.

Formality, tag-handling, formatting

This mock server does not implement these features, however the API input parameters are validated.

Model types

This mock server allows the quality-optimized models for all language pairs,
unlike the real DeepL API (which supports a subset of language pairs). Note that
as this mock server does not implement translation, the model type used has no
impact.

Billing period and usage limitations

This mock server always uses a fixed billing period for all accounts, beginning at 04:05:06.789 am on the 3rd day of the current month and ending at the same time on the 3rd day of the next month (UTC). Individual API key character counts are not tracked; all usage is simulated and does not reflect real consumption per key.

Additional checks compared with the DeepL API

User-Agent

This mock server rejects requests that do not include a non-empty User-Agent header, while the DeepL API accepts them.
To disable this check, set the mock-server-session-allow-missing-user-agent session header to non-zero.

Socket reconnections

To check that clients use Keep-Alive correctly, this mock server detects when a new socket is used for an
existing session and rejects these requests. Clients correctly using Keep-Alive should avoid these rejections.
To disable this check, set the mock-server-session-allow-reconnections session header to non-zero.

Issues

If you experience problems using the library, or would like to request a new feature, please open an
issue.

Development

We welcome Pull Requests, please read the contributing guidelines.