agentleFS
agenticlukeagenticluke/fsharp-test-kit-plus/skill/SKILL.md

fsharp-testing

Skill0 starsChanged 2 months agoMITView on GitHub

Test F# code with xUnit, FsUnit, Unquote, FsCheck, stubs, and .NET test tools.

7 other projects use a version of this, 7 of them edited.

Adopted by

Most recently taken up by

  • Other versions7 projects use a version of this.

    Word for word · 0

    None found.

    Wrote their own version · 0

    None found.

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

The file

Show its rules and text

We split this skill into the rules it gives an agent

25 rules. About 0 are common, 20 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈20

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use these steps to write clear and safe tests for F# code.

    line 9
  2. Distinctive:

    Use this skill when you:

    line 13
  3. Distinctive:

    Write new F# tests

    line 15
  4. Distinctive:

    Test an ASP.NET Core app

    line 20
  5. Distinctive:

    Do not add every tool by default.

    line 34
  6. Distinctive:

    Create a test project and add it to the solution:

    line 38
  7. Distinctive:

    Add test packages as needed:

    line 46
  8. Distinctive:

    Use one clear action in each test.

    line 66
  9. Distinctive:

    Use fresh data in each test.

    line 89
  10. Very specific:

    Do not use Thread.Sleep. Use a signal, a short Task.Delay, or a polling helper with a time limit.

    line 170
  11. Very specific:

    Use [<Theory>] for a short list of known cases.

    line 174
  12. Distinctive:

    Use FsCheck when a rule should hold for many inputs.

    line 195
  13. Very specific:

    Do not use any random decimal as money without limits.

    line 220
  14. Distinctive:

    Use a custom maker when most made-up values are not valid.

    line 224
  15. Distinctive:

    Keep a failing seed from the test output.

    line 241
  16. Distinctive:

    Create new state for each test.

    line 281
  17. Distinctive:

    Use a mock tool when the code must call a .NET interface.

    line 285
  18. Distinctive:

    Check calls only when the call is part of the real rule.

    line 319
  19. Very specific:

    Use WebApplicationFactory to test the full HTTP path.

    line 325
  20. Very specific:

    If Program cannot be seen by the test project, expose it from the app:

    line 349
  21. Distinctive:

    Use a unique database name for each test when using an in-memory database.

    line 355
  22. Distinctive:

    Keep unit tests fast. Keep service tests in a separate group if they need Docker, a network port, or a real database.

    line 363
  23. Distinctive:

    Check the cases that fit the code:

    line 441
  24. Distinctive:

    Do not test every item in this list for every function.

    line 459
  25. Distinctive:

    Test names state the rule

    line 505

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

F# Testing Patterns

Use these steps to write clear and safe tests for F# code.

When to Use This Skill

Use this skill when you:

  • Write new F# tests
  • Review test quality
  • Set up an F# test project
  • Fix slow or flaky tests
  • Test async code
  • Test an ASP.NET Core app

Pick the Right Tool

ToolUse
xUnitRun tests
FsUnit.xUnitWrite F# style checks
UnquoteShow clear test errors
FsCheck.XunitTest many made-up inputs
NSubstituteFake .NET interfaces
WebApplicationFactoryTest an ASP.NET Core app
TestcontainersTest with a real database or service

Do not add every tool by default. Add only what the tests need.

Set Up a Test Project

Create a test project and add it to the solution:

dotnet new xunit -lang F# -n MyApp.Tests -o tests/MyApp.Tests
dotnet sln add tests/MyApp.Tests/MyApp.Tests.fsproj
dotnet add tests/MyApp.Tests/MyApp.Tests.fsproj reference src/MyApp/MyApp.fsproj

Add test packages as needed:

dotnet add tests/MyApp.Tests package FsUnit.xUnit
dotnet add tests/MyApp.Tests package Unquote
dotnet add tests/MyApp.Tests package FsCheck.Xunit
dotnet add tests/MyApp.Tests package NSubstitute

F# files compile in the order shown in the .fsproj file. Put helper files before test files that use them.

<ItemGroup>
  <Compile Include="Helpers\TestData.fs" />
  <Compile Include="Unit\OrderTests.fs" />
</ItemGroup>

Write Small Unit Tests

Use one clear action in each test. Check the result that a caller can see.

module OrderTests

open Xunit
open FsUnit.Xunit

[<Fact>]
let ``create sets status to Pending`` () =
    let order = Order.create "cust-1" [ validItem ]

    order.Status |> should equal Pending

[<Fact>]
let ``confirm changes status to Confirmed`` () =
    let order = Order.create "cust-1" [ validItem ]

    let confirmed = Order.confirm order

    confirmed.Status |> should equal Confirmed

Use fresh data in each test. Do not let tests share data that can change.

Use Unquote for Clear Errors

Unquote shows which part of a check failed.

module OrderValidationTests

open Xunit
open Swensen.Unquote

[<Fact>]
let ``placeOrder accepts a valid request`` () =
    let request =
        { CustomerId = "cust-123"
          Items = [ validItem ] }

    let result = OrderService.placeOrder request

    test <@ Result.isOk result @>

[<Fact>]
let ``order total adds all item prices`` () =
    let items =
        [ { Sku = "A"; Quantity = 2; Price = 10m }
          { Sku = "B"; Quantity = 1; Price = 5m } ]

    let total = Order.calculateTotal items

    test <@ total = 25m @>

For Result, also check the value or error when it matters.

[<Fact>]
let ``empty email gives the right error`` () =
    let result = ValidatedEmail.create ""

    test <@ result = Error EmailIsEmpty @>

A check for only Result.isError may hide the wrong error.

Test Async Code

Return the task from the test. Do not call .Result or .Wait().

open Xunit
open Swensen.Unquote

[<Fact>]
let ``placeOrder saves a valid order`` () = task {
    let deps = createTestDeps ()
    let request =
        { CustomerId = "cust-123"
          Items = [ validItem ] }

    let! result = OrderService.placeOrder deps request

    test <@ Result.isOk result @>
}

Pass a CancellationToken when the code accepts one. Add a time limit to code that may hang.

[<Fact>]
let ``work stops when canceled`` () = task {
    use cts = new CancellationTokenSource()
    cts.Cancel()

    let work () = service.RunAsync(cts.Token)

    do! Assert.ThrowsAnyAsync<OperationCanceledException>(Func<Task>(work))
        :> Task
}

Do not use Thread.Sleep. Use a signal, a short Task.Delay, or a polling helper with a time limit.

Test More Than One Input

Use [<Theory>] for a short list of known cases.

open Xunit
open Swensen.Unquote

[<Theory>]
[<InlineData("", false)>]
[<InlineData("   ", false)>]
[<InlineData("user@example.com", true)>]
let ``email check returns the right result``
    (email: string)
    (expected: bool)
    =
    test <@ EmailValidator.isValid email = expected @>

InlineData can hold only simple constant values. Use MemberData, ClassData, or a normal [<Fact>] for records, lists, and other rich values.

Test Rules with FsCheck

Use FsCheck when a rule should hold for many inputs. Good rules include:

  • A value never goes below zero
  • Sorting keeps the same items
  • Encoding and decoding gives back the same value
  • Running an action twice has the same result as running it once
open FsCheck
open FsCheck.Xunit

[<Property>]
let ``order total is never negative``
    (items: NonEmptyList<PositiveInt * NonNegativeInt>)
    =
    let orderItems =
        items.Get
        |> List.map (fun (qty, price) ->
            { Sku = "SKU"
              Quantity = qty.Get
              Price = decimal price.Get })

    Order.calculateTotal orderItems >= 0m

Do not use any random decimal as money without limits. Very large values may cause overflow and hide the rule you meant to test.

Custom Value Makers

Use a custom maker when most made-up values are not valid.

type EmailGenerators =
    static member ValidEmail () =
        gen {
            let! user = Gen.elements [ "alice"; "bob"; "carol" ]
            let! host = Gen.elements [ "example.com"; "test.org" ]
            return $"{user}@{host}"
        }
        |> Arb.fromGen

[<Property(Arbitrary = [| typeof<EmailGenerators> |])>]
let ``valid emails pass the check`` (email: string) =
    EmailValidator.isValid email

Keep a failing seed from the test output. Use it to run the same failed case again while fixing the bug.

A save-and-load test needs a safe type. Make sure the type can be encoded, has a useful equality check, and does not hold functions or open resources.

[<Property>]
let ``JSON save and load keeps the order`` (order: Order) =
    let json = JsonSerializer.Serialize order
    let copy = JsonSerializer.Deserialize<Order> json

    copy = order

Prefer Function Stubs

F# code is often easy to test by passing functions as inputs.

type TestState =
    { mutable SavedOrders: Order list }

let createTestDeps state =
    { FindOrder = fun id ->
          task { return Map.tryFind id testOrders }
      SaveOrder = fun order ->
          task { state.SavedOrders <- order :: state.SavedOrders }
      SendNotification = fun _ ->
          Task.CompletedTask }

[<Fact>]
let ``placeOrder saves one order`` () = task {
    let state = { SavedOrders = [] }
    let deps = createTestDeps state

    let! _ = OrderService.placeOrder deps validRequest

    test <@ state.SavedOrders.Length = 1 @>
}

Create new state for each test. Shared mutable state can make tests fail based on run order.

Use NSubstitute for .NET Interfaces

Use a mock tool when the code must call a .NET interface.

open System
open System.Threading
open System.Threading.Tasks
open NSubstitute
open Xunit

[<Fact>]
let ``service asks for the right order ID`` () = task {
    let repo = Substitute.For<IOrderRepository>()

    repo
        .FindByIdAsync(
            Arg.Any<Guid>(),
            Arg.Any<CancellationToken>())
        .Returns(Task.FromResult(Some testOrder))
    |> ignore

    let service = OrderService(repo)

    let! _ =
        service.GetOrder(
            testOrder.Id,
            CancellationToken.None)

    do!
        repo.Received(1).FindByIdAsync(
            testOrder.Id,
            Arg.Any<CancellationToken>())
}

Check calls only when the call is part of the real rule. In most tests, check the returned value or saved state.

Be careful with overloads. Add type hints when F# cannot pick the right method.

Test an ASP.NET Core App

Use WebApplicationFactory to test the full HTTP path.

open System
open System.Net
open Microsoft.AspNetCore.Mvc.Testing
open Xunit
open Swensen.Unquote

type OrderApiTests(factory: WebApplicationFactory<Program>) =
    interface IClassFixture<WebApplicationFactory<Program>>

    let client = factory.CreateClient()

    [<Fact>]
    member _.``GET returns 404 for a missing order`` () = task {
        let id = Guid.NewGuid()

        let! response = client.GetAsync($"/api/orders/{id}")

        test <@ response.StatusCode = HttpStatusCode.NotFound @>
    }

If Program cannot be seen by the test project, expose it from the app:

type Program = class end

Use a unique database name for each test when using an in-memory database. A fixed name can leak data between tests.

let databaseName = $"TestDb-{Guid.NewGuid()}"

An in-memory database may act unlike the real database. Use Testcontainers for tests that depend on SQL rules, indexes, locks, time zones, or real database types.

Keep unit tests fast. Keep service tests in a separate group if they need Docker, a network port, or a real database.

Concrete Example

Code under test:

module Price

type Line =
    { Count: int
      UnitPrice: decimal }

let total lines =
    lines
    |> List.sumBy (fun line ->
        decimal line.Count * line.UnitPrice)

Tests:

module PriceTests

open Xunit
open Swensen.Unquote
open FsCheck
open FsCheck.Xunit

[<Fact>]
let ``total adds each line`` () =
    let lines =
        [ { Count = 2; UnitPrice = 4m }
          { Count = 1; UnitPrice = 3m } ]

    test <@ Price.total lines = 11m @>

[<Fact>]
let ``empty list has a zero total`` () =
    test <@ Price.total [] = 0m @>

[<Property>]
let ``total is not negative for safe values``
    (values: list<NonNegativeInt * NonNegativeInt>)
    =
    let lines =
        values
        |> List.map (fun (count, price) ->
            { Count = count.Get
              UnitPrice = decimal price.Get })

    Price.total lines >= 0m

This example checks one known case, one edge case, and one broad rule.

File Layout

tests/
  MyApp.Tests/
    Helpers/
      TestData.fs
      TestDeps.fs
    Unit/
      OrderServiceTests.fs
      PaymentServiceTests.fs
    Properties/
      OrderPropertyTests.fs
    Integration/
      OrderApiTests.fs
      OrderRepositoryTests.fs

List helper files first in the project file. Keep slow service tests apart from fast unit tests.

Edge Cases to Check

Check the cases that fit the code:

  • Empty strings and white space
  • Empty lists
  • Zero and negative numbers
  • The largest allowed number
  • Duplicate items
  • Missing values
  • Wrong IDs
  • Bad dates and time zones
  • Failed tasks
  • Canceled work
  • Time limits
  • Text with Unicode letters
  • Database errors
  • Two calls at the same time
  • Save and load failures

Do not test every item in this list for every function. Pick cases tied to real rules and risks.

Common Problems

ProblemBetter choice
Test private stepsTest results callers can see
Share mutable stateMake fresh state for each test
Use .Result or .Wait()Use let! in a task
Use Thread.SleepUse a signal or a time limit
Check only Result.isErrorCheck the exact error
Use random values with no limitsMake safe custom values
Use one database nameUse a new name per test
Depend on test run orderMake each test stand alone
Use a mock for pure codeCall the function at once
Hide a flaky test with retriesFind and fix the shared state or race
Use real clock timePass in a clock function
Use real random dataPass in a fixed seed or value source
Compare text made by sprintfCompare typed values when possible

Run Tests

# Run all tests
dotnet test

# Run one project
dotnet test tests/MyApp.Tests/MyApp.Tests.fsproj

# Run tests whose full name has OrderService
dotnet test --filter "FullyQualifiedName~OrderService"

# Run tests while files change
dotnet watch test --project tests/MyApp.Tests/MyApp.Tests.fsproj

# Collect code coverage
dotnet test --collect:"XPlat Code Coverage"

Coverage shows which code ran. It does not prove that the checks are good. Read the tests and test the key rules.

Final Check

Before you finish:

  • Each test has one clear reason to fail
  • Test names state the rule
  • Tests do not depend on run order
  • Async tests return a task
  • Slow work has a time limit
  • Errors are checked by kind and value
  • FsCheck inputs stay in safe limits
  • Integration tests clean up their data
  • The full test command passes

Related Skills

  • dotnet-patterns: Common .NET code and app design
  • csharp-testing: C# tests that may share .NET test tools

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.