Open-Source Testing · PSPDFKit-labs

bypass

Bypass is a lightweight Elixir library that spins up a mock HTTP server for testing. It lets you define prebaked responses to client requests without needing a real server, making it ideal for testing HTTP client behavior in isolation.

Talk to DEV.co Discuss Implementation

Source: GitHub — github.com/PSPDFKit-labs/bypass

998

GitHub stars

119

Forks

Elixir

Primary language

MIT

License (OSI-approved)

Key facts

Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.

Field	Value
Repository	PSPDFKit-labs/bypass
Owner	PSPDFKit-labs
Primary language	Elixir
License	MIT — OSI-approved
Stars	998
Forks	119
Open issues	27
Latest release	Unknown
Last updated	2025-07-10
Source	https://github.com/PSPDFKit-labs/bypass

What bypass is

Bypass is an Elixir/OTP plug-based mock server that intercepts HTTP requests and returns configured responses. It supports concurrent requests, route-specific expectations, dynamic port allocation, and state transitions (down/up) to simulate server failures.

Quickstart

Get the bypass source

Clone the repository and explore it locally.

terminalbash

1git clone https://github.com/PSPDFKit-labs/bypass.git2cd bypass3# follow the project's README for install & configuration

Need it deployed, integrated, or customized instead? DEV.co ships production installs.

Best use cases

Unit testing HTTP clients

Test how your Elixir HTTP client handles various status codes, error responses, and edge cases without depending on external services.

Integration testing with third-party APIs

Mock external API endpoints (e.g., Twitter, payment processors) to verify your application logic handles success and failure scenarios correctly.

Testing failure scenarios and recovery

Simulate server downtime, network errors, and reconnection logic using Bypass.down() and Bypass.up() to verify client resilience.

Implementation considerations

Bypass.open() must not be called in setup_all blocks; use per-test setup to ensure expectation verification works correctly.
Supports both ExUnit (default) and ESpec test frameworks; configure :bypass test_framework setting if using ESpec.
Multiple concurrent Bypass instances automatically allocate unique ports; pass the port to your HTTP client to connect.
Combine expect/expect_once (generic handlers) with expect/stub (route-specific) to handle fallback and specific route logic.
Enable :enable_debug_log in config to troubleshoot request routing and expectation matching during development.

When to avoid it — and what to weigh

Need production-grade mocking — Bypass is test-focused and not designed for production traffic interception or proxying.
Non-Elixir/OTP projects — Bypass requires Elixir 1.10+ and OTP 21+; it is not a language-agnostic mock server tool.
Complex HTTPS/TLS testing — Documentation does not clarify TLS/certificate handling; requires review for advanced SSL scenarios.
High-performance load testing — Bypass is optimized for test scenarios, not benchmarking or sustained high-concurrency load generation.

License & commercial use

MIT License (Expat): Permissive OSI-approved license. Allows commercial use, modification, and distribution with attribution and no warranty.

MIT License explicitly permits commercial use in derivative works. No copyleft restrictions. Verify you include a copy of the license and retain copyright notices in your project; legal review recommended for embedded/redistributed use.

DEV.co evaluation signals

Editorial assessment — not user reviews. Directional, with an explicit confidence level.

Signal	Assessment
Maintenance	Active
Documentation	Adequate
License clarity	Clear
Deployment complexity	Low
DEV.co fit	Good
Assessment confidence	High

Security considerations

Bypass is test-only and should never run in production. No encryption or certificate validation documented; suitable for local test environments. If testing TLS clients, verify how Bypass handles HTTPS—documentation is unclear on this aspect.

Alternatives to consider

Mox (Elixir)

Lighter-weight mocking library for behavior-driven unit tests; better for isolated unit testing without spinning up a server.

WireMock (JVM, language-agnostic)

HTTP mocking tool that supports multiple languages and provides a REST API for dynamic mock management; heavier but more feature-rich.

VCR (Ruby) / Exvcr (Elixir)

Records and replays HTTP interactions; reduces mock maintenance but introduces test coupling to recorded cassettes.

Software development agency

Build on bypass with DEV.co software developers

Bypass makes it simple to mock HTTP servers in your test suite. Let our Elixir experts help you integrate it into your testing strategy.

Talk to DEV.co

Related open-source tools

Surfaced by semantic similarity across the DEV.co open-source index.

faker mockttp mock-socket

Related on DEV.co

Explore the category and the services that help you build with it.

Open-Source Testing API Development Custom Software Development Talk to DEV.co

bypass FAQ

Can I use Bypass for production traffic?

No. Bypass is designed for test scenarios only and should never be deployed to production.

How does Bypass handle concurrent requests?

Bypass supports concurrent requests on the same instance and multiple concurrent Bypass instances. Each instance gets a unique dynamically allocated port.

Do I need to manually close the Bypass socket after each test?

No. Bypass automatically registers an on_exit hook with ExUnit to clean up sockets. ESpec users must explicitly call Bypass.verify_expectations! in a finally block.

What versions of Elixir and OTP are supported?

Elixir 1.10+ and OTP 21+. Bypass works with Cowboy 2.

Software development & web development with DEV.co

Need help beyond evaluating bypass? DEV.co is a software development agency offering software development services and web development for teams of every size. Our software developers and web developers build custom software, web applications, APIs, and open-source testing integrations — and maintain them long-term.

Need help testing your Elixir HTTP clients?

Bypass makes it simple to mock HTTP servers in your test suite. Let our Elixir experts help you integrate it into your testing strategy.

Talk to DEV.co Schedule a Consultation