From c4f4546fb8d2c7b47888a90da2e46bcb47203978 Mon Sep 17 00:00:00 2001 From: Liam Nichols Date: Sun, 25 Jun 2023 23:22:14 +0200 Subject: [PATCH] Documentation (#3) * Add initial documentation * Add workflow for pushing to GitHub pages * Fix tmp dir * fix script issues * only run on main branch --- .github/workflows/documentation.yml | 39 +++++++++++ .github/workflows/tests.yml | 4 +- Package.resolved | 18 +++++ Package.swift | 3 + Package@swift-5.9.swift | 1 + README.md | 4 ++ .../Documentation.docc/SwiftFixture.md | 69 +++++++++++++++++++ Sources/SwiftFixture/Fixture.swift | 2 +- 8 files changed, 137 insertions(+), 3 deletions(-) create mode 100644 .github/workflows/documentation.yml create mode 100644 Sources/SwiftFixture/Documentation.docc/SwiftFixture.md diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 0000000..4ec9057 --- /dev/null +++ b/.github/workflows/documentation.yml @@ -0,0 +1,39 @@ +name: "Documentation" + +on: + push: + branches: + - main + +jobs: + build: + name: Build Documentation + runs-on: macos-13 + env: + DEVELOPER_DIR: /Applications/Xcode_15.0.app/Contents/Developer + GENERATED_SITE_PATH: "/tmp/_site" + HOSTING_BASE_PATH: "https://liamnichols.eu/swift-fixture" + steps: + - name: Checkout Repo + uses: actions/checkout@v3 + - name: Build Documentation + run: swift package --allow-writing-to-directory "${{ env.GENERATED_SITE_PATH }}" generate-documentation --target SwiftFixture --disable-indexing --transform-for-static-hosting --hosting-base-path "${{ env.HOSTING_BASE_PATH }}" --output-path "${{ env.GENERATED_SITE_PATH }}" + - name: Upload Site + uses: actions/upload-pages-artifact@v1 + with: + path: ${{ env.GENERATED_SITE_PATH }} + + deploy: + name: Deploy Documentation + needs: build + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v2 diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index fa79ff6..f2e7b98 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -3,10 +3,10 @@ name: "Tests" on: push: branches: - - main + - main pull_request: branches: - - main + - main jobs: macos: diff --git a/Package.resolved b/Package.resolved index c4f9794..d650310 100644 --- a/Package.resolved +++ b/Package.resolved @@ -1,5 +1,23 @@ { "pins" : [ + { + "identity" : "swift-docc-plugin", + "kind" : "remoteSourceControl", + "location" : "https://github.com/apple/swift-docc-plugin", + "state" : { + "revision" : "26ac5758409154cc448d7ab82389c520fa8a8247", + "version" : "1.3.0" + } + }, + { + "identity" : "swift-docc-symbolkit", + "kind" : "remoteSourceControl", + "location" : "https://github.com/apple/swift-docc-symbolkit", + "state" : { + "revision" : "b45d1f2ed151d057b54504d653e0da5552844e34", + "version" : "1.0.0" + } + }, { "identity" : "swift-syntax", "kind" : "remoteSourceControl", diff --git a/Package.swift b/Package.swift index 8eff51b..83dd801 100644 --- a/Package.swift +++ b/Package.swift @@ -8,6 +8,9 @@ let package = Package( products: [ .library(name: "SwiftFixture", targets: ["SwiftFixture"]) ], + dependencies: [ + .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.3.0"), + ], targets: [ .target(name: "SwiftFixture"), .testTarget(name: "SwiftFixtureTests", dependencies: ["SwiftFixture"]) diff --git a/Package@swift-5.9.swift b/Package@swift-5.9.swift index 4143b64..a87ecd2 100644 --- a/Package@swift-5.9.swift +++ b/Package@swift-5.9.swift @@ -12,6 +12,7 @@ let package = Package( ], dependencies: [ .package(url: "https://github.com/apple/swift-syntax.git", from: "509.0.0-swift-5.9-DEVELOPMENT-SNAPSHOT-2023-04-25-b"), + .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.3.0"), ], targets: [ .target( diff --git a/README.md b/README.md index 7690ebb..216f668 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,9 @@ # SwiftFixture +[![Test Status](https://github.com/liamnichols/swift-fixture/workflows/Tests/badge.svg)](https://github.com/liamnichols/swift-fixture/actions/workflows/tests.yml) +[![Swift Language Compatibility](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fliamnichols%2Fswift-fixtures%2Fbadge%3Ftype%3Dswift-versions)](https://swiftpackageindex.com/liamnichols/swift-fixtures) +[![Platform Compatibility](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fliamnichols%2Fswift-fixtures%2Fbadge%3Ftype%3Dplatforms)](https://swiftpackageindex.com/liamnichols/swift-fixtures) + SwiftFixture is a tool to help you in writing clean and concise unit tests by standardizing the creation of fixture values. ## Overview diff --git a/Sources/SwiftFixture/Documentation.docc/SwiftFixture.md b/Sources/SwiftFixture/Documentation.docc/SwiftFixture.md new file mode 100644 index 0000000..016b609 --- /dev/null +++ b/Sources/SwiftFixture/Documentation.docc/SwiftFixture.md @@ -0,0 +1,69 @@ +# ``SwiftFixture`` + +A simple framework for managing test fixtures in Swift. + +## Overview + +SwiftFixture provides a set of tools designed to help make it easy for you to instantiate and organise values of your own Swift types for use as fixtures during unit testing. + +To recap, a [test fixture](https://en.wikipedia.org/wiki/Test_fixture) is an environment used to consistently test our software. For example: + +```swift +struct User { + var id: UUID + var name: String + var createdAt: Date + var isActive: Bool + // ... +} + +class SummaryTests: XCTestCase { + func testSummaryForActiveUser() { + let user = User(id: UUID(), name: "John", createdAt: Date(), isActive: true) + + let actual = getSummary(for: user) + let expected = "John is currently active" + + XCTAssertEqual(actual, expected) + } +} +``` + +In the `testSummaryForActiveUser()` example above, the `user` property is our test fixture that we rely on to test the behaviour of the `getSummary(for:)` method. Using the existing `User` initializer directly to create the fixture works, but over time you might start running into issues as your codebase matures. + +For example, you might already have noticed that the test is forced to reference the unused `id` and `createdAt` arguments. Additionally, if this practice was applied in multiple places, adding a new argument to the `User` initializer would require a large number of code changes across your tests, or worse, you could find yourself taking shortcuts with default values when you don't want to be. + +SwiftFixture aims to help provide a structure for creating fixtures that can scale with your codebase as it grows: + +```swift +class SummaryTests: XCTestCase { + let fixture = Fixture() + + func testSummaryForActiveUser() throws { + var user = try fixture(User.self) + user.isActive = true + + let actual = getSummary(for: user) + let expected = "\(user.name) is currently active" + + XCTAssertEqual(actual, expected) + } +} +``` + + +## Topics + +### Basics + +- ``Fixture`` + +### Registering Custom Types + +- ``FixtureProviding`` +- ``ProvideFixture()`` + +### Misc + +- ``PreferredFormat`` +- ``ResolutionError`` diff --git a/Sources/SwiftFixture/Fixture.swift b/Sources/SwiftFixture/Fixture.swift index c3e74f8..c7f9a61 100644 --- a/Sources/SwiftFixture/Fixture.swift +++ b/Sources/SwiftFixture/Fixture.swift @@ -62,7 +62,7 @@ open class Fixture { /// Creates a fixture instance with builtin fixture types using the preferred format provided. /// - /// - Parameter preferredFormat: The preferred format used when vending fixture values. Defaults to ``PreferredFormat.random``. + /// - Parameter preferredFormat: The preferred format used when vending fixture values. Defaults to ``PreferredFormat/random``. public init(preferredFormat: PreferredFormat = .random) { registerDefaults(using: preferredFormat) }