21GramConsulting/Beton
An enhancement built on top of Foundation Framework and XCTest. Performance test assertions and the magic ?! operator among many. We primarily use it for server-side engineering.
Beton
Beton is a Swift library built on top of
the Foundation framework, that provides an additional layer of
functionality, including easy localization, performance test measurement support, and convenience functionality.
For us, Beton is primarily, but not exclusively, useful for server-side Swift engineering.
Modules
- Beton: Generic purpose functionalities that may be useful for every application.
- XCTBeton: Extends the capabilities of XCTest by
providing assertions for performance measurements.
Using the Beton Module
Importing
To use Beton simply import it. If you need anything
from Foundation you do not need to explicitly import it. You get
it for free by importing Beton.
import BetonConvenience API for Bundle
Using Beton it is quite easy to get localized bundles and values from them.
Suppose you have a localization bundle in your project for the hu_HU locale, with a translation for "Apple" = "Alma"
, but you don't have one for "Banana" (which would be "Banán"). The following example finds the bundle, gets the
localized version of "Apple", and falls back to the given key "Banana".
let bundle = Bundle.module.localizationBundles["hu_HU"]
let localizedApple = bundle?.localizedString("Apple")
// localizedApple == "Alma"
let localizedBanana = bundle?.localizedString("Banana")
// localizedBanana == "Banana"Convenience API for Locale
Locales in Beton are expressible by string literals.
let locales: [Locale] = ["en_US", "en_GB", "hu_HU"]
for locale in locales {
print("Currency symbol: \(locale.currencySymbol ?? "N/A")")
}
// Prints:
// Currency symbol: $
// Currency symbol: £
// Currency symbol: Ft?! operator
The ?! operator unwraps an Optional value if is
not nil, otherwise throws the given error.
struct GenericError: Error {}
let answer = try Int("42") ?! GenericError()
// answer == 42
try Int("NaN") ?! GenericError()
// Throws: GenericError()sum extension on Sequences
Calculates the total of all elements in a sequence. Available on any sequence with values that conform
to AdditiveArithmetic
let arraySum = [1.1, 2.2, 3.3, 4.4, 5.5].sum()
// arraySum == 16.5
let rangeSum = (1..<10).sum()
// rangeSum == 45
let setSum = Set(arrayLiteral: 1, 2, 3, 2, 3).sum()
// setSum == 6Convenience for Measurements
In Beton measurements have default units and they conform
to AdditiveArithmetic.
let sum = [1, 2, 3].map { Measurement<UnitLength>(value: $0, unit: .default) }.sum()
// sum == 6.0 mUsing the XCTBeton Module
Let's say you have a simple performance test that measures some code.
Using XCTest there is no easy,
straightforward way to make assertions to the performance results.
import XCTest
class PerformanceTests: XCTestCase {
func test_measureSum() {
measure {
let _ = (1..<1000).reduce(0, +)
}
// Performance assertions needed!
}
}You can turn this code into an XCTBeton test by simply changing the import. Yes, that's it. You can now make
assertions!
import XCTBeton
class PerformanceTests: XCTestCase {
func test_measureSum() {
measure {
let _ = (1..<1000).reduce(0, +)
}
XCTAssertMetric(.clock, .timeMonotonic, .average(maximum: 0.001))
}
}If you want to control the type of measurements, and how many times the tests run you can do that using the same API as
you would in regular XCTest.
import XCTBeton
class PerformanceTests: XCTestCase {
func test_measureSum() {
let options = XCTMeasureOptions()
options.iterationCount = 100
measure(metrics: [XCTCPUMetric(), XCTMemoryMetric()], options: options) {
let _ = (1..<1000).reduce(0, +)
}
XCTAssertMetric(.cpu, .time, .average(maximum: 0.002))
XCTAssertMetric(.cpu, .cycles, .average(maximum: 2000))
XCTAssertMetric(.memory, .physical, .average(maximum: 20))
}
}Adding Beton as a Dependency
To use the Beton library in a SwiftPM project, add it to the dependencies for your package and your target. Your
target can depend on either the Beton or XCTBeton modules, or both.
// swift-tools-version:5.5.0
import PackageDescription
let package = Package(
name: "MyApplication",
dependencies: [
.package(url: "https://github.com/21GramConsulting/Beton", from: "1.0.0"),
],
targets: [
.target(name: "MyApplication", dependencies: [
.product(name: "Beton", package: "Beton"),
.product(name: "XCTBeton", package: "Beton"),
])
]
)