Then run bundle install.

The default mode in development and test is to disallow all HTTP network connections. This provides a clean foundation for consuming new services. If you add a new service integration, the first thing that you will be presented with when you attempt to hit it in development or test is a warning that the requested URL was not mocked. This behavior comes straight outta WebMock.

The first thing to do is run the install generator.

This will drop a new file in your config directory.

If you're not using Rails, you can create this file for yourself.

Next, you will want create a FakeService and register it with the framework.

This can be accomplished by running the fake service generator:

This will generate a file fake_bank.rb in the top-level folder webvalve. This file will be autoloaded by Rails, so you can tweak it as you go without having to restart your application.

And it will automatically register it in config/webvalve.rb

Again, if you're not using Rails, you'll have to create this file yourself and update the config file manually.

You'll also want to define an environment variable for the base url of your service.

That's it. Now when you hit your service again, it will route your request into the FakeBank instance.

If you want to connect to the actual service, all you have to do is set another environment variable.

You will have to restart your application after making this change because service faking is an initialization time concern and not a runtime concern.

In order to get WebValve fake services working properly in tests, you have to configure WebValve at the beginning of each test. For RSpec, there is a configuration provided.

If you are using rspec-retry, you'll have to manually register your around hook, instead, to ensure that WebValve resets its configuration for each retry, e.g.:

For any other test framework, you will want to similarly set up webmock lifecycle hooks, and add a custom hook that will run WebValve.setup before each test.

Given a scenario where we want to mock a specific behavior for an endpoint in a test, we can just use WebMock(tm).

In other scenarios where we don't care about the specific response from the endpoint, you can just lean into the behavior you've configured for that route in your fake service.

Sometimes a service integration may want to use an unconventional name for its environment variables. In that case, you can register the fake service using the optional url: argument.

If the service you are interacting with contains dynamic elements, e.g. an instance-specific subdomain, you can specify a wildcard in your url with the * character to match a series of zero or more characters within the same URL segment. For example:

or

Note: unlike filesystem globbing, ? isn't respected to mean "exactly one character" because it's a URL delimiter character. Only * works for WebValve URL wildcards.

Alternatively you can use Addressable::Templates or Regexps to specify dynamic URLs if they for some reason aren't a good fit for the wildcard syntax. Note that there is no ENV var support for these formats because there is no detection logic to determine a URL string is actually meant to represent a URL template or regexp. For example:

or

The definition of FakeService is really simple. It's just a Sinatra::Base class. It is wired up to support returning JSON responses and it will raise when a route is requested but it is not registered.

Can I use WebValve in environments like staging, demo, and production?

Yes! By default WebValve is only enabled in test and development environments; however, it can be enabled in other environments by setting WEBVALVE_ENABLED=true (actually, any of 1/t/true will work). This can be useful for spinning up cheap, one-off environments for user-testing or demos. When WebValve is enabled in any environment other than development/test it will default services to enabled rather than disabled, allowing all traffic to pass-thru. This ensures that production-like environments are run integrated by default. You can change this behavior by setting WEBVALVE_SERVICE_ENABLED_DEFAULT=false (any of 0/f/false will work). This will default to the same experience as local development, defaulting services to disabled, intercepting all traffic. In either of these modes, you can use the $SERVICE_ENABLED=true/false to toggle a specific service into the desired state.

Can I use WebValve without Rails?

Yep! If you're not using Rails, you'll have to load the config file yourself. You will want to explicitly require each of your fake services in your config/webvalve.rb, require your config file, and call WebValve.setup during your app's boot-up process.

We would love for you to contribute! Anything that benefits the majority of webvalve users--from a documentation fix to an entirely new feature--is encouraged.

Before diving in, check our issue tracker and consider creating a new issue to get early feedback on your proposed change.

• Fork the project and create a new branch for your contribution.
• Write your contribution (and any applicable test coverage).
• Make sure all tests pass (bundle exec rake).
• Submit a pull request.