How do I record network requests with Vinyl for my Swift tests?

Configure a Turntable with recordingMode like .missingVinyl or .missingTracks, and optionally set a recordingPath. Vinyl will save requests and responses as JSON fixtures when matches aren't found, as explained in the Recording section.

Vinyl vs DVR for iOS unit testing: which is better?

Vinyl offers more flexible request matching and recording features compared to DVR's strict approach. It also supports DVR cassette compatibility, making it a versatile upgrade for teams wanting less brittle tests.

Can I use Vinyl with Alamofire in my Swift project?

Yes, by initializing a custom SessionManager with a URLSession from Vinyl's Turntable, as detailed in the 'Coming from Alamofire' section. This allows seamless integration for testing Alamofire-based network layers.

How to create custom tracks programmatically in Vinyl?

Use TrackFactory.createValidTrack to manually create tracks with custom URLs, bodies, and headers, enabling dynamic response mocking without relying on JSON files, as shown in the README examples.

Does Vinyl automatically record missing tracks during tests?

Yes, with recordingMode set to .missingTracks, Vinyl records new tracks to an existing vinyl where no match is found, saving them to the specified path for future test runs.

What are the matching strategies available in Vinyl?

Vinyl supports mapping by request attributes like URL, method, body, and query, or a track-order queue approach, configurable via MatchingStrategy.enum with types such as .url or .custom.

Open-Awesome

Vinyl

MITSwift0.10.4

A flexible Swift library for replaying HTTP requests in unit tests, inspired by VCR.

GitHub

269 stars28 forks0 contributors

What is Vinyl?

Vinyl is a Swift library for replaying HTTP requests in unit tests, similar to VCR in Ruby. It allows developers to record and playback network interactions, ensuring tests are fast, reliable, and independent of external services. It solves the problem of flaky network-dependent tests by providing pre-recorded responses.

Target Audience

iOS, macOS, and tvOS developers who write unit tests for network-heavy applications and use dependency injection in their architecture.

Value Proposition

Developers choose Vinyl for its flexibility in request matching, support for multiple recording modes, and compatibility with existing DVR cassettes, making it a versatile alternative to stricter mocking libraries.

Overview

Network testing à la VCR in Swift

Use Cases

Best For

Unit testing network layers in Swift apps with dependency injection
Replaying pre-recorded HTTP responses to simulate API behavior
Migrating from DVR to a more flexible Swift testing library
Recording real network requests to generate test fixtures automatically
Testing Alamofire-based networking code with custom URL sessions
Ensuring network tests are deterministic and fast by avoiding live calls

Not Ideal For

Apps with tightly coupled network layers where URLSession is hardcoded and not injectable
Teams requiring strict, exact request matching for compliance or security-critical tests
Projects needing immediate, out-of-the-box debugging tools for network interactions

Pros & Cons

Pros

Flexible Matching Strategies

Supports both attribute-based mapping and queue-based track ordering, with customizable matchers for URL, body, headers, etc., as detailed in the MatchingStrategy examples.

Recording for Fixture Generation

Includes recording modes like .missingVinyl and .missingTracks to automatically generate test fixtures from real network requests, saving time on manual setup.

DVR Cassette Compatibility

Offers a compatibility mode to reuse existing DVR cassettes without rewriting tests, easing migration from older libraries.

Custom Track Creation

Allows programmatic creation of tracks using TrackFactory, not just JSON files, enabling dynamic response mocking in tests.

Cons

Pre-Release Stability

Marked as a pre-release version with pending features like debug mode on the roadmap, which may lead to instability or breaking changes.

Dependency Injection Dependency

Optimized for apps with dependency injection; using it with fixed URLSession architectures requires workarounds or is not recommended, per the README.

Limited Debugging Support

Debug mode is listed as a roadmap item and not yet implemented, hindering troubleshooting during test development or failure analysis.

Open Source Alternative To

Vinyl is an open-source alternative to the following products:

VCR

VCR is a library for recording and replaying HTTP interactions in tests, available in multiple languages like Ruby, JavaScript, and Python.

DVR

Digital Video Recorder technology that allows recording of television programs to a hard drive or other storage medium for later viewing.

Frequently Asked Questions

Related Projects

SnapshotTesting

📸 Delightful Swift snapshot testing.

Stars4,327

Forks680

Last commit14 days ago

iOS Snapshot Test Case

Snapshot view unit tests for iOS

Stars1,863

Forks227

Last commit9 months ago

Fakery

:alien: Swift fake data generator

Stars1,824

Forks186

Last commit3 years ago

Cuckoo

Boilerplate-free mocking framework for Swift!

Stars1,743

Forks200

Last commit2 days ago

Community-curated · Updated weekly · 100% open source

Found a gem we're missing?

Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.

Submit a project Star on GitHub