Download the PHP package ciareis/bypass without Composer

About | Requirements | Installation | Writing Tests | API Reference | Examples | Troubleshooting | Contributing | Credits | Inspired

About

Requirements

• PHP: 8.2 or higher (tested up to PHP 8.4)
• Composer: For dependency management

Known Issues

• PHP 8.4: You may see deprecation warnings from testing dependencies (Pest/PHPUnit) related to ReflectionMethod::setAccessible(). These warnings are harmless and come from the testing frameworks themselves, not from Bypass. They will be resolved when the dependencies are updated to support PHP 8.4 fully.

Installation

To install via composer, run the following command:

Video demo

Pest and Bypass

Writing Tests

Content

• Open Bypass Server
• Bypass URL and Port
• Routes
  • Standard Route
  • File Route
  • Bypass Serve and Route Helpers
• Assert Route
• Stop or shut down

🔥 Check out full code examples here section.

1. Open a Bypass Server

To write a test, first open a Bypass server:

Bypass will always run at http://localhost listening to a random port number.

To specify a custom port, just pass it in the argument (int) $port.

Alternative method: You can also use Bypass::up() which is an alias for Bypass::open():

2. Bypass URL and Port

You can retrieve the Bypass server URL using getBaseUrl().

If you need to retrieve only the port number, use the getPort() method:

3. Routes

Bypass provides two types of routes: The Standard Route to return a text body content and the File Route, which returns a binary file.

When running your test suit, you should pass the URL created with Bypass to your service. In this way, you will make the service you are testing reach Bypass instead of reaching the real-world API end point.

3.1 Standard Route

The method addRoute() accepts the following parameters:

3.2 File Route

The method addFileRoute() accepts the following parameters:

3.3 Bypass Serve and Route Helpers

Bypass provides you with convenient shortcuts to the most-common-used HTTP requests.

These shortcuts are called "Route Helpers" and are served automatically at a random port using Bypass::serve() without the need to call Bypass::open().

In the next example, Bypasss serves two routes: A URL accessible by method GET returning a JSON body with status 200, and a second route URL accessible by method GET and returning status 404.

Route Helpers

You may find below the list of Route Helpers.

You may also adjust the helpers to your needs by passing arguments:

In the example below, you can see the Helper Route::badRequest using method GET instead of its default method POST.

📝 Note: Custom routes can be created using a Standard Route in case something you need is not covered by the Helpers.

4. Asserting Route Calling

Sometimes you may need to assert that a route was called at least one or multiple times.

The method assertRoutes() will return a RouteNotCalledException if a route was NOT called as many times as defined in the $times parameter.

If you need to assert that a route is NOT being called by your service, set the parameter $times = 0

5. Stop or shut down

Bypass will automatically stop its server once your test is done running.

The Bypass server can be stopped or shut down at any point with the following methods:

To stop: $bypass->stop();

To shut down: $bypass->down();

API Reference

Methods

Static Methods

• Bypass::open(?int $port = null): self
  Opens a new Bypass server instance. If no port is specified, a random port will be used.

• Bypass::up(?int $port = null): self
  Alias for open(). Opens a new Bypass server instance.

• Bypass::serve(...$routes): self
  Creates and serves multiple routes at once. Accepts Route objects, RouteFile objects, or arrays.

Instance Methods

• addRoute(string $method, string $uri, int $status = 200, string|array|null $body = null, int $times = 1, array $headers = []): self
  Adds a standard route that returns text/JSON content.

• expect(string $method, string $uri, int $status = 200, string|array|null $body = null, int $times = 1, array $headers = []): self
  Alias for addRoute(). Adds a standard route that returns text/JSON content.

• addFileRoute(string $method, string $uri, int $status = 200, ?string $file = null, int $times = 1, array $headers = []): self
  Adds a file route that returns binary file content.

• getRoutes(): array
  Returns all registered routes as an array of route configurations.

• assertRoutes(): void
  Asserts that all registered routes were called the expected number of times. Throws RouteNotCalledException if any route was not called as expected.

• getBaseUrl(?string $path = null): string
  Returns the base URL of the Bypass server. Optionally appends a path.

• getPort(): int
  Returns the port number the Bypass server is listening on.

• stop(): self
  Stops the Bypass server by clearing all routes. The server process remains running.

• down(): self
  Shuts down the Bypass server process completely.

Exceptions

RouteNotCalledException

Thrown when assertRoutes() is called and a route was not called the expected number of times.

Examples

Use case

To better illustrate Bypass usage, imagine you have to write a test for a service that calculates the total game score of a given username.

The score is obtained by making an external request to a fictitious API at emtudo-games.com/v1/score/::USERNAME::. The API returns HTTP Status 200 and a JSON body with a list of games:

Quick Test Examples

Click below to see code snippets for Pest PHP and PHPUnit.

Test Examples

📚 See Bypass being used in complete tests with Pest PHP and PHPUnit for the GithubRepoService demo service.

Advanced Examples

Using Custom Headers

Multiple Route Calls

Handling Exceptions

Troubleshooting

Common Issues

Port Already in Use

If you specify a port that's already in use, Bypass will fail to start. Use a random port (default) or ensure the port is available:

Server Timeout

Bypass has a default timeout of 5 seconds for server startup. If your system is slow, the server might not start in time. This is rare but can happen in CI environments.

Route Not Found Errors

If you're getting "route not found" errors, ensure:

• The URI matches exactly (including query parameters)
• The HTTP method matches (GET, POST, etc.)
• The route was added before making the request
• The service is using the correct Bypass URL

Getting All Registered Routes

You can inspect all registered routes for debugging:

Contributing

We welcome contributions! Here's how you can help:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes following the existing code style
4. Add tests for new functionality
5. Ensure all tests pass: vendor/bin/pest
6. Commit your changes: git commit -m 'Add amazing feature'
7. Push to the branch: git push origin feature/amazing-feature
8. Open a Pull Request

Code Style

• Follow PSR-12 coding standards
• Use type hints where possible
• Add PHPDoc comments for public methods
• Write tests for new features

Testing

• Run tests with: vendor/bin/pest
• Ensure all tests pass before submitting a PR
• Add tests for any new functionality

Credits

• Leandro Henrique
• All Contributors

And a special thanks to @DanSysAnalyst

Inspired

Code inspired by Bypass