### Development Setup with Filtered Tests

Source: https://github.com/haf/expecto/blob/main/_autodocs/configuration.md

Example command for local development using `dotnet watch` with test filtering and color output.

```bash
dotnet watch run -- --filter "unit" --colours 256 --no-spinner
```

--------------------------------

### CI/CD Setup with Strict Mode

Source: https://github.com/haf/expecto/blob/main/_autodocs/configuration.md

Example command for CI/CD environments, enabling strict mode with NUnit summary generation and error verbosity.

```bash
dotnet run -- \
  --fail-on-focused-tests \
  --nunit-summary TestResults.xml \
  --verbosity Error \
  --sequenced
```

--------------------------------

### Complex Setup and Teardown with Functions

Source: https://github.com/haf/expecto/blob/main/README.md

Manage complex setup and teardown scenarios by writing dedicated setup functions. These functions can inject dependencies and handle resource management for multiple tests.

```fsharp
let clientTests setup =
    [
        test "test1" {
            setup (fun client store ->
                // test code
            )
        }
        test "test2" {
            setup (fun client store ->
                // test code
            )
        }
        // other tests
    ]

let clientMemoryTests =
    clientTests (fun test ->
        let client = memoryClient()
        let store = memoryStore()
        test client store
    )
    |> testList "client memory tests"

let clientIntegrationTests =
    clientTests (fun test ->
        // setup code
        try
            let client = realTestClient()
            let store = realTestStore()
            test client store
        finally
            // teardown code
    )
    |> testList "client integration tests"
```

--------------------------------

### Setup Compiler State

Source: https://github.com/haf/expecto/blob/main/CONTRIBUTING.md

Source environment variables and run the fake build script for compiler setup.

```bash
source .env
./fake 
```

--------------------------------

### Complete Example with All Features

Source: https://github.com/haf/expecto/blob/main/_autodocs/api-reference/test-runners.md

A comprehensive example demonstrating how to use various Expecto features, including defining tests, configuring the runner, and running tests with command-line arguments.

```APIDOC
## Complete Example with All Features

### Description
Demonstrates a complete test suite setup with various Expecto features and command-line usage.

### Code Example
```fsharp
open Expecto
open System

[<Tests>]
let allTests =
  testList "complete suite" [
    testCase "math" <| fun () ->
      Expect.equal (2 + 2) 4 "addition"

    testSequenced <| testCase "database" <| fun () ->
      Expect.equal 1 1 "isolated test"

    ftestCase "focused" <| fun () ->
      Expect.equal 1 1 "only this runs when focused"

    ptestCase "pending" <| fun () ->
      Expect.equal 1 1 "skipped"
  ]

[<EntryPoint>]
let main argv =
  let config =
    { defaultConfig with
        verbosity = LogLevel.Verbose
        failOnFocusedTests = true }

  // Can also use: runTestsInAssemblyWithCLIArgs [] argv
  runTestsWithCLIArgs [] argv allTests
```

### Typical CLI Usage
```bash
# Run all tests
dotnet run

# Run tests matching "math"
dotnet run -- --filter math

# Run with 2 workers sequentially
dotnet run -- --sequenced --parallel-workers 2

# Stress test for 5 minutes
dotnet run -- --stress 5.0

# Generate NUnit XML
dotnet run -- --nunit-summary TestResults.xml

# Debug mode with verbose output
dotnet run -- --debug

# List all tests without running
dotnet run -- --list-tests

# Fail if focused tests exist
dotnet run -- --fail-on-focused-tests
```
```

--------------------------------

### Create Test Cases with Setup Function

Source: https://github.com/haf/expecto/blob/main/_autodocs/api-reference/test-builders.md

Use testFixture to generate multiple test cases from a setup function and a sequence of name-value pairs. The setup function prepares resources for each test.

```fsharp
val testFixture : setup:('a -> (unit -> unit)) -> (string * 'a) seq -> Test seq
```

```fsharp
let withStream f () =
  use ms = new System.IO.MemoryStream()
  f ms

let streamTests =
  testList "stream tests" (
    testFixture withStream [
      "can read", fun ms -> Expect.equal ms.CanRead true "should be readable"
      "can write", fun ms -> Expect.equal ms.CanWrite true "should be writable"
    ] |> List.ofSeq
  )
```

--------------------------------

### String does not start with prefix

Source: https://github.com/haf/expecto/blob/main/_autodocs/errors.md

Indicates that Expect.stringStarts failed because the subject string did not start with the expected prefix.

```fsharp
message. Expected subject string to start with the prefix. Differs at position N 
with subject 'X' and prefix 'Y'.
```

--------------------------------

### Complete Expecto Test Suite Example

Source: https://github.com/haf/expecto/blob/main/_autodocs/api-reference/test-runners.md

A comprehensive example demonstrating various Expecto features including test lists, sequenced tests, focused tests, pending tests, and advanced configuration. Shows how to run tests with CLI arguments.

```fsharp
open Expecto
open System

[<Tests>]
let allTests =
  testList "complete suite" [
    testCase "math" <| fun () ->
      Expect.equal (2 + 2) 4 "addition"

    testSequenced <| testCase "database" <| fun () ->
      Expect.equal 1 1 "isolated test"

    ftestCase "focused" <| fun () ->
      Expect.equal 1 1 "only this runs when focused"

    ptestCase "pending" <| fun () ->
      Expect.equal 1 1 "skipped"
  ]

[<EntryPoint>]
let main argv =
  let config =
    { defaultConfig with
        verbosity = LogLevel.Verbose
        failOnFocusedTests = true }

  // Can also use: runTestsInAssemblyWithCLIArgs [] argv
  runTestsWithCLIArgs [] argv allTests
```

```bash
# Run all tests
dotnet run

# Run tests matching "math"
dotnet run -- --filter math

# Run with 2 workers sequentially
dotnet run -- --sequenced --parallel-workers 2

# Stress test for 5 minutes
dotnet run -- --stress 5.0

# Generate NUnit XML
dotnet run -- --nunit-summary TestResults.xml

# Debug mode with verbose output
dotnet run -- --debug

# List all tests without running
dotnet run -- --list-tests

# Fail if focused tests exist
dotnet run -- --fail-on-focused-tests
```

--------------------------------

### Setup and Teardown with IDisposable

Source: https://github.com/haf/expecto/blob/main/README.md

Implement `IDisposable` for resources to automatically handle setup and teardown within test cases. This ensures resources are properly cleaned up after each test.

```fsharp
let simpleTests =
    testList "simples" [
        test "test one" {
            use resource = new MyDatabase()
            // test code
        }
    ]
```

--------------------------------

### F# Example Code Snippet

Source: https://github.com/haf/expecto/blob/main/_autodocs/INDEX.md

A basic, runnable example of F# code demonstrating a function call. This follows the general code example convention for the documentation.

```fsharp
// Complete, runnable examples
let example = someFunction()
```

--------------------------------

### Advanced Function Speed Comparison with Setup

Source: https://github.com/haf/expecto/blob/main/_autodocs/api-reference/performance-module.md

Use `isFasterThanSub` for performance comparisons that require setup or teardown logic. This allows for more control over the measurement environment.

```fsharp
val Expect.isFasterThanSub : f1:(Performance.Measurer<unit, 'a> -> 'a) -> f2:(Performance.Measurer<unit, 'a> -> 'a) -> message:string -> unit
```

```fsharp
let dbPerformanceTest = testSequenced <| testCase "query performance" <| fun () ->
  Expect.isFasterThanSub
    (fun measurer ->
      use conn = getConnection()
      measurer (fun () -> queryOptimized conn) ())
    (fun measurer ->
      use conn = getConnection()
      measurer (fun () -> queryUnoptimized conn) ())
    "optimized query should be faster"
```

--------------------------------

### testFixture

Source: https://github.com/haf/expecto/blob/main/_autodocs/api-reference/test-builders.md

Creates multiple test cases from a setup function and a sequence of (name, value) pairs. The setup function is executed for each test case, and the resource it creates is available to the test function.

```APIDOC
## testFixture

### Description
Creates multiple test cases from a setup function and a sequence of (name, value) pairs.

### Parameters
#### Path Parameters
- setup ('a -> (unit -> unit)) - Required - Function that sets up the resource and runs the test
- (string * 'a) seq - Required - Pairs of test names and values to test

### Returns
`Test seq` — Sequence of test cases

### Example
```fsharp
let withStream f ()
  use ms = new System.IO.MemoryStream()
  f ms

let streamTests =
  testList "stream tests" (
    testFixture withStream [
      "can read", fun ms -> Expect.equal ms.CanRead true "should be readable"
      "can write", fun ms -> Expect.equal ms.CanWrite true "should be writable"
    ] |> List.ofSeq
  )
```
```

--------------------------------

### Asynchronous Test Fixture Example

Source: https://github.com/haf/expecto/blob/main/README.md

Use testFixtureAsync for tests requiring asynchronous setup and teardown. The factory function returns an Async block that provides the resource.

```fsharp
testList "Setup & teardown 4" [
  let withMemoryStream f = async {
    use ms = new MemoryStream()
    do! f ms
  }
  yield! testFixtureAsync withMemoryStream [
    "can read",
      fun ms -> async { return ms.CanRead ==? true }
    "can write",
      fun ms -> async { return ms.CanWrite ==? true }
  ]
]
```

--------------------------------

### Example Test Case Focus States

Source: https://github.com/haf/expecto/blob/main/_autodocs/types.md

Illustrates creating `TestCase` instances with different `FocusState` values.

```fsharp
let focusedTest = TestCase(testCode, Focused)  // only this runs
let pendingTest = TestCase(testCode, Pending)   // always skipped
let normalTest = TestCase(testCode, Normal)     // conditional
```

--------------------------------

### Create a .NET Project with Expecto Template

Source: https://github.com/haf/expecto/blob/main/README.md

Install the Expecto.Template and create a new Expecto project. Replace PROJECT_NAME and FOLDER_NAME with your desired project and folder names.

```bash
dotnet new install 'Expecto.Template::*'
dotnet new expecto -n PROJECT_NAME -o FOLDER_NAME
```

--------------------------------

### Advanced Performance Tests with Setup

Source: https://github.com/haf/expecto/blob/main/_autodocs/api-reference/performance-module.md

Demonstrates advanced performance testing using `isFasterThanSub` for comparing binary search against findIndex, and for loop against List.iter.

```fsharp
let advancedPerformanceTests = testSequenced <| testList "advanced performance" [
  testCase "query performance comparison" <| fun () ->
    let data = Array.init 100000 (fun i -> i)

    Expect.isFasterThanSub
      (fun measurer ->
        let sorted = Array.sort data
        measurer (fun () -> Array.binarySearch sorted 50000) ())
      (fun measurer ->
        measurer (fun () -> Array.findIndex ((=) 50000) data) ())
      "binary search should be faster"

  testCase "collection iteration" <| fun () ->
    Expect.isFasterThan
      (fun () ->
        let mutable sum = 0
        for i in [1..10000] do sum <- sum + i
        sum)
      (fun () ->
        let mutable sum = 0
        List.iter (fun i -> sum <- sum + i) [1..10000]
        sum)
      "for loop should be faster"
]
```

--------------------------------

### Configure FsCheck Start Size

Source: https://github.com/haf/expecto/blob/main/_autodocs/configuration.md

Set the starting size for FsCheck test generation using --fscheck-start-size. Defaults to 1.

```bash
--fscheck-start-size N
  Set FsCheck start size (default: 1).
  Type: Integer
  Default: 1
```

--------------------------------

### F# Inline Documentation Example

Source: https://github.com/haf/expecto/blob/main/_autodocs/INDEX.md

An example of inline documentation within F# code, showing how to reference external documentation sections. This helps developers quickly find relevant API details.

```fsharp
// See test-builders.md#ftestcase
let focusedTest = ftestCase "..." ...
```

--------------------------------

### Example Test Composition

Source: https://github.com/haf/expecto/blob/main/_autodocs/types.md

Demonstrates the creation of various `Test` types, including `TestCase`, `TestList`, `TestLabel`, and `Sequenced`.

```fsharp
let test1 = TestCase(Sync (fun () -> ()), Normal)
let test2 = TestCase(Sync (fun () -> ()), Normal)
let list = TestList([test1; test2], Normal)
let labeled = TestLabel("math", list, Normal)
let sequenced = Sequenced(Synchronous, labeled)
```

--------------------------------

### Run a Simple Expecto Test Case

Source: https://github.com/haf/expecto/blob/main/README.md

Define and run a basic Expecto test case. This example demonstrates a simple string equality assertion.

```fsharp
open Expecto

let tests =
  test "A simple test" {
    let subject = "Hello World"
    Expect.equal subject "Hello World" "The strings should equal"
  }

[<EntryPoint>]
let main args =
  runTestsWithCLIArgs [] args tests
```

--------------------------------

### Running tests and checking result

Source: https://github.com/haf/expecto/blob/main/_autodocs/errors.md

Example of how to run tests using a runner and interpret the exit code.

```fsharp
let result = runTestsWithCLIArgs [] argv tests
// Returns 0 on all pass
// Returns 1 on any failure (AssertException, etc.)
```

--------------------------------

### FsCheckConfig Example Usage

Source: https://github.com/haf/expecto/blob/main/_autodocs/types.md

Demonstrates how to create and modify an FsCheckConfig instance, specifically setting the maximum number of test cases.

```fsharp
let config = { FsCheckConfig.defaultConfig with maxTest = 10000 }
```

--------------------------------

### Task-based Test Fixture Example

Source: https://github.com/haf/expecto/blob/main/README.md

Use testFixtureTask for tests needing setup and teardown that return a Task. The factory function returns a Task block providing the resource.

```fsharp
testList "Setup & teardown 5" [
  let withMemoryStream f = task {
    use ms = new MemoryStream()
    do! f ms
  }
  yield! testFixtureTask withMemoryStream [
    "can read",
      fun ms -> task { return ms.CanRead ==? true }
    "can write",
      fun ms -> task { return ms.CanWrite ==? true }
  ]
]
```

--------------------------------

### stringStarts

Source: https://github.com/haf/expecto/blob/main/_autodocs/api-reference/expect-module.md

Asserts that a string starts with a specified prefix. Provides colored diff on failure.

```APIDOC
## stringStarts

### Description
Asserts that a string starts with a prefix. Provides colored diff on failure.

### Method
N/A (F# function)

### Signature
```fsharp
val stringStarts : subject:string -> prefix:string -> message:string -> unit
```

### Parameters
- **subject** (string) - The string to check.
- **prefix** (string) - The prefix the string should start with.
- **message** (string) - The error message to display if the assertion fails.

### Example
```fsharp
Expect.stringStarts url "https://" "URL should use HTTPS"
```
```

--------------------------------

### Basic Property Tests with FsCheck

Source: https://github.com/haf/expecto/blob/main/README.md

Demonstrates basic property tests for addition and list reversal using Expecto and FsCheck. Includes an example of overriding FsCheck configuration.

```fsharp
module MyApp.Tests

// the ExpectoFsCheck module is auto-opened by this
// the configuration record is in the Expecto namespace in the core library
open Expecto

let config = { FsCheckConfig.defaultConfig with maxTest = 10000 }

let properties = 
  testList "FsCheck samples" [
    testProperty "Addition is commutative" <| fun a b ->
      a + b = b + a

    testProperty "Reverse of reverse of a list is the original list" <|
      fun (xs:list<int>) -> List.rev (List.rev xs) = xs

    // you can also override the FsCheck config
    testPropertyWithConfig config "Product is distributive over addition" <|
      fun a b c ->
        a * (b + c) = a * b + a * c
  ]

Tests.runTestsWithCLIArgs [] [||] properties

```

--------------------------------

### TestsAttribute Example Usage

Source: https://github.com/haf/expecto/blob/main/_autodocs/types.md

Shows how to apply the TestsAttribute to a test list.

```fsharp
[<Tests>]
let myTests = testList "tests" [ ... ]
```

--------------------------------

### Assert String Starts With Prefix

Source: https://github.com/haf/expecto/blob/main/_autodocs/api-reference/expect-module.md

Asserts that a string starts with a specified prefix. Provides a colored diff on failure for easier debugging.

```fsharp
val stringStarts : subject:string -> prefix:string -> message:string -> unit
```

```fsharp
Expect.stringStarts url "https://" "URL should use HTTPS"
```

--------------------------------

### Analyze Performance Measurement Statistics

Source: https://github.com/haf/expecto/blob/main/_autodocs/api-reference/performance-module.md

Example of how to use `Performance.timeStatistics` to gather and display performance metrics for a given operation.

```fsharp
let stats = Performance.timeStatistics (fun measurer -> measurer f ())
printfn "Time: %.2f ± %.2f ms (N=%d)" stats.mean stats.meanStandardError stats.N
```

--------------------------------

### Install Expecto Packages with Paket

Source: https://github.com/haf/expecto/blob/main/README.md

Add the necessary Expecto packages to your project's dependencies file when using Paket.

```text
nuget Expecto
nuget Expecto.BenchmarkDotNet
nuget Expecto.FsCheck
nuget Expecto.Hopac
```

--------------------------------

### PTestsAttribute Example Usage

Source: https://github.com/haf/expecto/blob/main/_autodocs/types.md

Shows how to use the PTestsAttribute on a test list.

```fsharp
[<PTests>]
let pendingTests = testList "pending" [ ... ]
```

--------------------------------

### Miscellaneous Configuration Options

Source: https://github.com/haf/expecto/blob/main/_autodocs/api-reference/test-runners.md

Additional configuration options for debugging, logging, version information, and test name handling. Command-line examples demonstrate their usage.

```fsharp
| Debug
| Log_Name of name:string
| Verbosity of LogLevel
| Version
| Allow_Duplicate_Names
| JoinWith of split: string
| Printer of TestPrinters
| Append_Summary_Handler of SummaryHandler
```

```bash
--debug
--log-name MyTests
--version
--allow-duplicate-names
--join-with /
```

--------------------------------

### Standard Expecto API Assertions

Source: https://github.com/haf/expecto/blob/main/_autodocs/api-reference/flip-expect-fluent-api.md

Provides examples of common assertion functions available in the standard Expecto.Expect module.

```fsharp
open Expecto

Expect.equal actual expected message
Expect.isTrue value message
Expect.stringContains subject substring message
```

--------------------------------

### Basic Test Example

Source: https://github.com/haf/expecto/blob/main/_autodocs/README.md

A simple F# test case using Expecto's 'test' builder and 'Expect.equal' assertion. This is the main entry point for running tests with CLI arguments.

```fsharp
open Expecto

let simpleTest =
  test "math works" {
    Expect.equal (2 + 2) 4 "2+2=4"
  }

[<EntryPoint>]
let main argv =
  runTestsWithCLIArgs [] argv simpleTest
```

--------------------------------

### FTestsAttribute Example Usage

Source: https://github.com/haf/expecto/blob/main/_autodocs/types.md

Illustrates applying the FTestsAttribute to a test list.

```fsharp
[<FTests>]
let focusedTests = testList "focused" [ ... ]
```

--------------------------------

### Complete Fluent API Test Suite

Source: https://github.com/haf/expecto/blob/main/_autodocs/api-reference/flip-expect-fluent-api.md

A comprehensive example showcasing various fluent assertions including equality, boolean checks, options, results, floats, and exceptions.

```fsharp
open Expecto
open Expecto.Flip

let fluentTests =
  testList "fluent style" [
    test "equality" {
      42 |> Expect.equal "answer" 42 |> ignore
    }

    test "boolean" {
      (10 > 5) |> Expect.isTrue "should be true" |> ignore
    }

    test "option" {
      Some 42 |> Expect.isSome "should be Some" |> ignore
      let value = Some 100 |> Expect.wantSome "should extract" 
      value |> Expect.equal "should be 100" 100 |> ignore
    }

    test "result" {
      Result.Ok 42 |> Expect.isOk "should succeed" |> ignore
      let value = Result.Ok 99 |> Expect.wantOk "should extract"
      value |> Expect.equal "should be 99" 99 |> ignore
    }

    test "float comparison" {
      3.14159 
        |> Expect.floatClose "π close to 3.14160" Accuracy.high 3.14160
        |> ignore
    }

    test "exception" {
      (fun () -> raise (ArgumentException "test"))
        |> Expect.throws "should throw"
        |> ignore
    }
  ]
```

--------------------------------

### Synchronous Test Fixture Example

Source: https://github.com/haf/expecto/blob/main/README.md

Use testFixture to set up and tear down resources for synchronous tests. The factory function provides the resource to the test case.

```fsharp
testList "Setup & teardown 3" [
  let withMemoryStream f () =
    use ms = new MemoryStream()
    f ms
  yield! testFixture withMemoryStream [
    "can read",
      fun ms -> ms.CanRead ==? true
    "can write",
      fun ms -> ms.CanWrite ==? true
  ]
]
```

--------------------------------

### Pending Tests Example

Source: https://github.com/haf/expecto/blob/main/README.md

Demonstrates various ways to mark tests and test lists as pending using 'p' prefixes or the P attribute, preventing them from running.

```fsharp
open Expecto

[<PTests>]
let skippedTestFromReflectionDiscovery = testCase "skipped" <| fun () ->
    Expect.equal (2+2) 4 "2+2"

[<Tests>]
let myTests =
  testList "normal" [
    testList "unfocused list" [
      ptestCase "skipped" <| fun () -> Expect.equal (2+2) 1 "2+2?"
      testCase "will run" <| fun () -> Expect.equal (2+2) 4 "2+2"
      ptest "skipped" { Expect.equal (2+2) 1 "2+2?" }
      ptestAsync "skipped async" { Expect.equal (2+2) 1 "2+2?" }
    ]
    testCase "will run" <| fun () -> Expect.equal (2+2) 4 "2+2"
    ptestCase "skipped" <| fun () -> Expect.equal (2+2) 1 "2+2?"
    ptestList "skipped list" [
      testCase "skipped" <| fun () -> Expect.equal (2+2) 1 "2+2?"
      ftest "skipped" { Expect.equal (2+2) 1 "2+2?" }
    ]
  ]
```

--------------------------------

### Assert Sequence Starts With Prefix

Source: https://github.com/haf/expecto/blob/main/_autodocs/api-reference/expect-module.md

Use this to verify that a sequence begins with a specified sequence of elements. The order of elements in the prefix must match the beginning of the subject sequence.

```fsharp
Expect.sequenceStarts [1; 2; 3; 4] [1; 2] "should start with [1; 2]"
```

--------------------------------

### Handling AssertException within a test

Source: https://github.com/haf/expecto/blob/main/_autodocs/errors.md

Example of how to catch and handle an AssertException within a test case using a try-with block.

```fsharp
testCase "example" <| fun () ->
  try
    Expect.equal 1 2 "should fail"
  with
  | :? AssertException as ex ->
    // This catches the exception if you want to handle it
    printfn "Caught: %s" ex.Message
    // Re-throw or handle
    reraise()
```

--------------------------------

### Configure Logary for Expecto Logging

Source: https://github.com/haf/expecto/blob/main/README.md

Integrate Logary for enhanced logging and stacktrace highlighting with Expecto. This setup configures Logary to use a console target and process events.

```fsharp
open Hopac
open Logary
open Logary.Configuration
open Logary.Adapters.Facade
open Logary.Targets

[<EntryPoint>]
let main argv =
  let logary =
    Config.create "MyProject.Tests" "localhost"
    |> Config.targets [ LiterateConsole.create LiterateConsole.empty "console" ]
    |> Config.processing (Events.events |> Events.sink ["console";])
    |> Config.build
    |> run
  LogaryFacadeAdapter.initialise<Expecto.Logging.Logger> logary

  // Invoke Expecto:
  runTestsInAssemblyWithCLIArgs [] argv
```

--------------------------------

### Performance Testing with Expect.isFasterThan

Source: https://github.com/haf/expecto/blob/main/_autodocs/README.md

Example of performance testing using 'testSequenced' and 'Expect.isFasterThan' to compare the execution time of two functions. Requires 'largeArray' and 'largeList' to be defined elsewhere.

```fsharp
let perfTests =
  testSequenced <| testList "performance" [
    test "array faster than list" <| fun () ->
      Expect.isFasterThan
        (fun () -> Array.sort largeArray)
        (fun () -> List.sort largeList)
        "array should be faster"
  ]
```

--------------------------------

### Control Output and Reporting

Source: https://github.com/haf/expecto/blob/main/_autodocs/api-reference/test-runners.md

Options to control test output formatting and report generation, including summary formats, color support, and listing tests. Command-line examples are provided for various options.

```fsharp
| Summary
| Summary_Location
| NUnit_Summary of string
| JUnit_Summary of string
| Colours of int
| No_Spinner
| List_Tests of listStates: FocusState list
```

```bash
--summary
--summary-location
--nunit-summary TestResults.xml
--junit-summary results.junit.xml
--colours 256
--no-spinner
--list-tests
```

--------------------------------

### List Tests Instead of Running

Source: https://github.com/haf/expecto/blob/main/_autodocs/configuration.md

Use --list-tests to display a list of tests without executing them. Optionally filter by state (Normal, Focused, Pending). Example: --list-tests Normal Focused.

```bash
--list-tests [STATE...]
  Don't run tests, but prints out list of tests instead. 
  Lists only tests with specified state(s), or all tests if not.
  States: Normal, Focused, Pending
  Example: --list-tests Normal Focused
  Type: List of states (optional)
```

--------------------------------

### Display Help Information

Source: https://github.com/haf/expecto/blob/main/_autodocs/README.md

Access the command-line help for Expecto by using the --help flag. This provides a comprehensive overview of available options.

```bash
dotnet run -- --help
```

--------------------------------

### Chain Configuration Methods

Source: https://github.com/haf/expecto/blob/main/_autodocs/configuration.md

Shows how to chain multiple configuration methods to build a complex configuration, including adding summary handlers.

```fsharp
// Chain methods
let config =
  defaultConfig
    .AddNUnitSummary("TestResults.xml")
    .AddJUnitSummary("results.junit.xml")
    .appendSummaryHandler(fun summary ->
      printfn "Tests: %d passed, %d failed"
        summary.passed.Length summary.failed.Length)
```

--------------------------------

### Create Custom Configuration by Modifying Defaults

Source: https://github.com/haf/expecto/blob/main/_autodocs/configuration.md

Demonstrates how to create a custom configuration by modifying specific properties of the default configuration.

```fsharp
// Modify default config
let customConfig =
  { defaultConfig with
      runInParallel = false
      verbosity = LogLevel.Debug
      colour = Colour256 }

runTestsWithCLIArgs [] argv tests
```

--------------------------------

### Display Version Information

Source: https://github.com/haf/expecto/blob/main/_autodocs/configuration.md

Print the Expecto version information using the --version flag.

```bash
--version
  Print out version information.
  Type: Flag
```

--------------------------------

### Initialize Logary Facade Adapter

Source: https://github.com/haf/expecto/blob/main/_autodocs/README.md

Integrate Expecto logging with Logary by initializing the LogaryFacadeAdapter. This ensures Expecto logs are routed through Logary.

```fsharp
open Logary.Adapters.Facade

LogaryFacadeAdapter.initialise<Expecto.Logging.Logger> logary
// Expecto logs flow through Logary
```

--------------------------------

### Run Console Apps with CLI Args

Source: https://github.com/haf/expecto/blob/main/README.md

Demonstrates how to execute console applications with specific command-line arguments programmatically. This is useful for automated testing or scripting.

```fsharp
Tests.runTestsInAssemblyWithCLIArgs [Stress 0.1;Stress_Timeout 0.2] [||]
```

--------------------------------

### Programmatic CLI Arguments

Source: https://github.com/haf/expecto/blob/main/_autodocs/configuration.md

Illustrates how to define command-line arguments programmatically using a sequence of arguments.

```fsharp
// Programmatic CLI arguments
let args = seq {
  yield Parallel_Workers 4
  yield Verbosity LogLevel.Debug
  yield Fail_On_Focused_Tests
}

runTestsWithCLIArgs args argv tests
```

--------------------------------

### Show Help Message

Source: https://github.com/haf/expecto/blob/main/_autodocs/configuration.md

Display the help message using --help, -h, -?, or /?.

```bash
--help, -h, -?, /?
  Show help message.
  Type: Flag
```

--------------------------------

### Advanced Performance Assertion

Source: https://github.com/haf/expecto/blob/main/_autodocs/api-reference/expect-module.md

An advanced variant for performance assertions that allows for custom setup, teardown, and measurement configurations.

```fsharp
val isFasterThanSub : f1:(Performance.Measurer<unit, 'a> -> 'a) -> f2:(Performance.Measurer<unit, 'a> -> 'a) -> message:string -> unit
```

--------------------------------

### isFasterThanSub

Source: https://github.com/haf/expecto/blob/main/_autodocs/api-reference/performance-module.md

An advanced variant of `isFasterThan` that supports setup and teardown phases, and allows for fine-grained control over the measurement process.

```APIDOC
## isFasterThanSub

### Description
An advanced variant of `isFasterThan` that supports setup and teardown phases, and allows for fine-grained control over the measurement process. This function is useful for more complex performance tests where setup or specific measurement configurations are needed.

### Signature
```fsharp
val Expect.isFasterThanSub : f1:(Performance.Measurer<unit, 'a> -> 'a) -> f2:(Performance.Measurer<unit, 'a> -> 'a) -> message:string -> unit
```

### Parameters
#### Parameters
- **f1** (Performance.Measurer<unit, 'a> -> 'a) - Required - The first function, which takes a `Measurer` and performs the operation to be timed.
- **f2** (Performance.Measurer<unit, 'a> -> 'a) - Required - The second function, which also takes a `Measurer` and performs the operation to be timed.
- **message** (string) - Required - An error message to display if the test fails.

### Example
```fsharp
let dbPerformanceTest = 
  testSequenced <| testCase "query performance" <| fun () ->
    Expect.isFasterThanSub
      (fun measurer -> 
        use conn = getConnection()
        measurer (fun () -> queryOptimized conn) ())
      (fun measurer -> 
        use conn = getConnection()
        measurer (fun () -> queryUnoptimized conn) ())
      "optimized query should be faster"
```
```

--------------------------------

### testCaseTask

Source: https://github.com/haf/expecto/blob/main/_autodocs/api-reference/test-builders.md

Builds an asynchronous test case from a function returning a Task. The function is deferred to prevent the task from starting immediately.

```APIDOC
## testCaseTask

### Description
Builds an asynchronous test case from a function returning a Task. The function is deferred to prevent the task from starting immediately.

### Signature
```fsharp
val testCaseTask : name:string -> test:(unit -> Task<unit>) -> Test
```

### Parameters
#### Parameters
- **name** (string) - Required - The test name
- **test** (unit -> Task<unit>) - Required - A function that returns a task to execute

### Returns
`Test`

### Example
```fsharp
let taskTest =
  testCaseTask "task-based test" <| fun () -> task {
    let! n = Task.FromResult 42
    Expect.equal n 42 "task result should be 42"
  }
```
```

--------------------------------

### Define and Run a Simple Expecto Test

Source: https://github.com/haf/expecto/blob/main/README.md

This snippet shows how to define a test case using `testCase` and run it using `runTestsWithCLIArgs`. The `Expect.equal` function is used for assertion.

```fsharp
open Expecto

let simpleTest =
  testCase "A simple test" <| fun () ->
    let expected = 4
    Expect.equal expected (2+2) "2+2 = 4"
```

```fsharp
runTestsWithCLIArgs [] [||] simpleTest
```

--------------------------------

### testFixtureAsync, testFixtureTask

Source: https://github.com/haf/expecto/blob/main/_autodocs/api-reference/test-builders.md

Asynchronous and task-based variants of testFixture, allowing setup functions that return `Async<unit>` or `Task<unit>` respectively.

```APIDOC
## testFixtureAsync, testFixtureTask

### Description
Async and task variants of test fixtures.

### Signature
```fsharp
val testFixtureAsync : setupAsync:('a -> Async<unit>) -> (string * 'a) seq -> Test seq
val testFixtureTask : setupTask:('a -> Task<unit>) -> (string * 'a) seq -> Test seq
```
```

--------------------------------

### Specify Test Name Separator

Source: https://github.com/haf/expecto/blob/main/_autodocs/configuration.md

Define the separator for test names using --join-with. Can be '.' (default) or '/'. Example: --join-with /.

```bash
--join-with SEPARATOR
  Specify test names join character.
  Can be "." (default) or "/".
  Example: --join-with /
  Type: String ("." or "/")
  Default: "."
```

--------------------------------

### Initialize Custom Logger with Logary

Source: https://github.com/haf/expecto/blob/main/_autodocs/configuration.md

Integrates custom logging by initializing the Logary facade adapter with a custom configuration.

```fsharp
open Logary
open Logary.Adapters.Facade

let logary =
  Config.create "MyApp.Tests" "localhost"
  |> Config.targets [ LiterateConsole.create LiterateConsole.empty "console" ]
  |> Config.processing (Events.events |> Events.sink ["console"])
  |> Config.build
  |> run

LogaryFacadeAdapter.initialise<Expecto.Logging.Logger> logary

// Now run tests
runTestsInAssemblyWithCLIArgs [] argv
```

--------------------------------

### Assert Option is Some and Get Value

Source: https://github.com/haf/expecto/blob/main/_autodocs/api-reference/expect-module.md

Use `Expect.wantSome` to assert that an option is `Some` and immediately extract its contained value. If the option is `None`, the test fails.

```fsharp
let result = Dict.tryFind key dict
let value = Expect.wantSome result "key should exist"
// can now use `value`
```

--------------------------------

### Enable Test Summary Output

Source: https://github.com/haf/expecto/blob/main/_autodocs/configuration.md

Use --summary to print a summary after all tests complete. Use --summary-location to include source code locations in the summary.

```bash
--summary
  Print out a summary after all tests are finished.
  Type: Flag

--summary-location
  Print out a summary after all tests are finished including 
  their source code location.
  Type: Flag
```

--------------------------------

### Open Expecto.Flip Module

Source: https://github.com/haf/expecto/blob/main/_autodocs/api-reference/flip-expect-fluent-api.md

Opens the Expecto.Flip module for using the fluent API. Typically used with piping.

```fsharp
open Expecto.Flip
```

--------------------------------

### Filter Test Lists by Substring

Source: https://github.com/haf/expecto/blob/main/_autodocs/configuration.md

Use --filter-test-list with a substring to narrow down test lists. For example, --filter-test-list "math".

```bash
--filter-test-list SUBSTRING
  Filters the list of test lists by a given substring.
  Example: --filter-test-list "math"
  Type: String
```

--------------------------------

### Fluent Flip.Expect API Assertions

Source: https://github.com/haf/expecto/blob/main/_autodocs/api-reference/flip-expect-fluent-api.md

Demonstrates equivalent assertion functions using the fluent API from Expecto.Flip.Expect, showing the pipe-first syntax.

```fsharp
open Expecto.Flip

actual |> Expect.equal message expected
value |> Expect.isTrue message
subject |> Expect.stringContains message substring
```

--------------------------------

### Filter Tests by Hierarchy

Source: https://github.com/haf/expecto/blob/main/_autodocs/configuration.md

Use --filter with a slash-separated hierarchy to select specific tests. For example, --filter "math/addition".

```bash
--filter HIERARCHY
  Filters the list of tests by a hierarchy that's slash (/) separated.
  Example: --filter "math/addition"
  Type: String
```

--------------------------------

### Organizing Tests with Test Lists

Source: https://github.com/haf/expecto/blob/main/_autodocs/README.md

Demonstrates how to group multiple tests into logical suites using 'testList'. This allows for better organization and modularity of test suites.

```fsharp
let mathTests =
  testList "math" [
    test "addition" { Expect.equal (1 + 1) 2 "1+1=2" }
    test "subtraction" { Expect.equal (5 - 3) 2 "5-3=2" }
  ]

let myTests =
  testList "main suite" [
    mathTests
    otherTests
  ]
```

--------------------------------

### Assert Result is Ok and Get Value

Source: https://github.com/haf/expecto/blob/main/_autodocs/api-reference/expect-module.md

Use `Expect.wantOk` to assert that a `Result` is `Ok` and extract its contained value. If the result is `Error`, the test fails.

```fsharp
let result = tryParseInt "42"
let value = Expect.wantOk result "should parse"
Expect.equal value 42 "parsed value"
```

--------------------------------

### Publish Expecto.Template NuGet Package

Source: https://github.com/haf/expecto/blob/main/Expecto.Template/CONTRIBUTING.md

This PowerShell script automates the process of packing the Expecto.Template project and publishing it to NuGet. Ensure you replace 'your-api-key' with your actual NuGet API key.

```powershell
$nugetApiKey = 'your-api-key'
rm ./bin/Release/*.nupkg
dotnet pack -c Release -o ./bin/Release/
ls ./bin/Release/*.nupkg |% { dotnet nuget push $_ --source https://api.nuget.org/v3/index.json --api-key $nugetApiKey}
```

--------------------------------

### Configure Stress Test Duration

Source: https://github.com/haf/expecto/blob/main/_autodocs/configuration.md

Run tests randomly for a specified duration in minutes using the --stress argument. Example: --stress 5.0.

```bash
--stress MINUTES
  Run the tests randomly for the given number of minutes.
  Example: --stress 5.0
  Type: Float
  Default: None
```

--------------------------------

### Filter Test Cases by Substring

Source: https://github.com/haf/expecto/blob/main/_autodocs/configuration.md

Use --filter-test-case with a substring to select specific test cases. For example, --filter-test-case "addition".

```bash
--filter-test-case SUBSTRING
  Filters the list of test cases by a given substring.
  Example: --filter-test-case "addition"
  Type: String
```

--------------------------------

### sequenceStarts

Source: https://github.com/haf/expecto/blob/main/_autodocs/api-reference/expect-module.md

Asserts that a sequence begins with a specified prefix sequence. This is helpful for validating the initial elements of a collection.

```APIDOC
## sequenceStarts

### Description
Asserts that a sequence starts with a prefix.

### Method
N/A (Function Call)

### Parameters
- **subject** (seq<'a>) - Required - The sequence to check.
- **prefix** (seq<'a>) - Required - The prefix sequence.
- **message** (string) - Required - The error message to display if the assertion fails.

### Example
```fsharp
Expect.sequenceStarts [1; 2; 3; 4] [1; 2] "should start with [1; 2]"
```
```

--------------------------------

### Generate NUnit Summary File

Source: https://github.com/haf/expecto/blob/main/_autodocs/README.md

Execute tests and generate an NUnit-compatible summary file. Specify the output file path using --nunit-summary.

```bash
dotnet run -- --nunit-summary TestResults.xml
```

--------------------------------

### Release Build Command

Source: https://github.com/haf/expecto/blob/main/CONTRIBUTING.md

Execute the fake build script with the Release target for project releases.

```bash
./fake build -- --target Release
```

--------------------------------

### Run Tests with Programmatic and CLI Arguments

Source: https://github.com/haf/expecto/blob/main/_autodocs/api-reference/test-runners.md

Use `runTestsWithCLIArgs` to execute tests with both explicit configuration and command-line arguments. This is the primary entry point for running tests programmatically.

```F#
val runTestsWithCLIArgs : cliArgs:CLIArguments seq -> args:string[] -> tests:Test -> int
```

```F#
[<EntryPoint>]
let main argv =
  let tests =
    testList "my tests" [
      testCase "test 1" <| fun () -> Expect.equal 1 1 "one equals one"
    ]
  runTestsWithCLIArgs [] argv tests
```

--------------------------------

### Generate JUnit Summary File

Source: https://github.com/haf/expecto/blob/main/_autodocs/README.md

Execute tests and generate a JUnit-compatible summary file. Specify the output file path using --junit-summary.

```bash
dotnet run -- --junit-summary results.junit.xml
```

--------------------------------

### Add NUnit Summary to Configuration

Source: https://github.com/haf/expecto/blob/main/_autodocs/configuration.md

Configures Expecto to generate NUnit-format XML test results at a specified path.

```fsharp
val AddNUnitSummary : path:string -> ExpectoConfig
```

```fsharp
let config = defaultConfig.AddNUnitSummary("TestResults.xml")
runTestsWithCLIArgs [] argv tests
// File TestResults.xml is created after tests complete
```

--------------------------------

### Handling Timeout Failures in Expecto

Source: https://github.com/haf/expecto/blob/main/_autodocs/errors.md

Tests exceeding the duration set by `Test.timeout` will result in an `AssertException "Timeout (<duration>)"`. This example demonstrates setting a 1-second timeout for a test that takes longer.

```fsharp
let slowTest = 
  testCase "slow operation" <| fun () ->
    Thread.Sleep(5000)
    Expect.equal 1 1 "done"
  |> Test.timeout 1000  // 1 second timeout

// Result: AssertException "Timeout (00:00:01)"
```

--------------------------------

### Add JUnit Summary to Configuration

Source: https://github.com/haf/expecto/blob/main/_autodocs/configuration.md

Configures Expecto to generate JUnit-format XML test results.

```fsharp
val AddJUnitSummary : path:string -> ExpectoConfig
```

```fsharp
let config = defaultConfig.AddJUnitSummary("junit-results.xml")
```

--------------------------------

### Default Expecto Configuration

Source: https://github.com/haf/expecto/blob/main/_autodocs/api-reference/test-runners.md

The `defaultConfig` provides a baseline Expecto configuration that can be modified. It includes settings for parallelism, verbosity, and more.

```F#
val defaultConfig : ExpectoConfig
```

--------------------------------

### Configure Mailgun Logging with Expecto

Source: https://github.com/haf/expecto/blob/main/README.md

Set up Logary with Mailgun target to send email notifications for test failures. Ensure Logary is initialized correctly with the facade.

```fsharp
open Logary
open Logary.Configuration
open Logary.Adapters.Facade
open Logary.Targets
open Hopac
open Mailgun
open System.Net.Mail

let main argv =
  let mgc =
    MailgunLogaryConf.Create(
      MailAddress("travis@example.com"),
      [ MailAddress("Your.Mail.Here@example.com") ],
      { apiKey = "deadbeef-2345678" },
      "example.com", // sending domain of yours
      Error) // cut-off level

  use logary =
    withLogaryManager "MyTests" (
      withTargets [
        LiterateConsole.create LiterateConsole.empty "stdout"
        Mailgun.create mgc "mail"
      ]
      >> withRules [
        Rule.createForTarget "stdout"
        Rule.createForTarget "mail"
      ])
    |> run

  // initialise Logary Facade with Logary proper:
  LogaryFacadeAdapter.initialise<Expecto.Logging.Logger> logary

  // run all tests
  Tests.runTestsInAssemblyWithCLIArgs [] argv
```

--------------------------------

### Generate NUnit and JUnit Test Reports

Source: https://github.com/haf/expecto/blob/main/_autodocs/README.md

Run tests and generate NUnit and JUnit summary files. Ensure TestResults.xml and results.xml are specified as output files.

```bash
dotnet run -- --nunit-summary TestResults.xml --junit-summary results.xml
```

--------------------------------

### Property-Based Testing Configuration

Source: https://github.com/haf/expecto/blob/main/_autodocs/configuration.md

Command-line arguments for configuring property-based testing with FsCheck, specifying test counts and sizes.

```bash
dotnet run -- \
  --fscheck-max-tests 10000 \
  --fscheck-end-size 5000 \
  --filter "property"
```

--------------------------------

### Cancelling tests with CancellationToken

Source: https://github.com/haf/expecto/blob/main/_autodocs/errors.md

Demonstrates how to use a CancellationTokenSource to cancel running tests gracefully.

```fsharp
let cts = new CancellationTokenSource()
let result = runTestsWithCLIArgsAndCancel cts.Token [] argv tests
cts.Cancel()  // Cancels running tests

**Effect:** Running tests stop gracefully; pending tests don't start

**No exception thrown** unless cancellation callbacks fail
```

--------------------------------

### Run .NET Watch with Specific Project and Target Framework

Source: https://github.com/haf/expecto/blob/main/README.md

Use `dotnet watch` to continuously run tests for a specific project and target framework. Ensure the project path and framework are correctly specified.

```bash
dotnet watch -p MyProject.Tests run -f net10.0
```

--------------------------------

### Local Development with Detailed Output

Source: https://github.com/haf/expecto/blob/main/_autodocs/configuration.md

Command for local development with detailed logging, single parallel worker, and specific test filtering.

```bash
dotnet run -- \
  --debug \
  --summary-location \
  --colours 256 \
  --parallel-workers 1 \
  --filter "math"
```

--------------------------------

### Alternative Syntax for Expecto Test Case Definition

Source: https://github.com/haf/expecto/blob/main/README.md

Demonstrates an alternative syntax for defining a test case using a lambda function, equivalent to the `<|` operator.

```fsharp
testCase "A simple test" (fun () ->
  Expect.equal 4 (2+2) "2+2 should equal 4")
```

--------------------------------

### Configure Stress Testing Options

Source: https://github.com/haf/expecto/blob/main/_autodocs/api-reference/test-runners.md

Defines options for stress testing, such as duration and memory limits. Use command-line arguments like --stress, --stress-timeout, and --stress-memory-limit.

```fsharp
| Stress of float
| Stress_Timeout of float
| Stress_Memory_Limit of float
```

```fsharp
// Run tests randomly for 5 minutes
runTestsWithCLIArgs [Stress 5.0] argv tests
```

--------------------------------

### Complete Performance Test Suite

Source: https://github.com/haf/expecto/blob/main/_autodocs/api-reference/performance-module.md

A comprehensive set of performance tests using `testSequenced` and `testList`, including comparisons for sorting and finding optimal buffer sizes.

```fsharp
open Expecto

let performanceTests = testSequenced <| testList "performance" [
  testCase "sort array is faster than sort list" <| fun () ->
    let arr = Array.init 1000 (fun i -> 1000 - i)
    let lst = List.init 1000 (fun i -> 1000 - i)

    Expect.isFasterThan
      (fun () -> Array.sort arr; arr)
      (fun () -> List.sort lst)
      "Array should be faster"

  testCase "find fastest buffer size" <| fun () ->
    let data = Array.init 10000 (fun i -> i)

    let f bufferSize =
      let mutable sum = 0
      for i = 0 to data.Length - 1 do
        sum <- sum + data.[i % bufferSize]
      sum

    let optimal = Performance.findFastest f 1 1024
    Expect.isGreaterThan optimal 0 "buffer size should be positive"
]
```

--------------------------------

### BenchmarkDotNet Integration

Source: https://github.com/haf/expecto/blob/main/README.md

Integrates Expecto with BenchmarkDotNet for performance measurement. Define serialisers with varying sleep times and benchmark their performance. Ensure tests run sequentially or disable parallelism for accurate results.

```fsharp
open Expecto

type ISerialiser =
  abstract member Serialise<'a> : 'a -> unit

type MySlowSerialiser() =
  interface ISerialiser with
    member __.Serialise _ =
      System.Threading.Thread.Sleep(30)

type FastSerialiser() =
  interface ISerialiser with
    member __.Serialise _ =
      System.Threading.Thread.Sleep(10)

type FastSerialiserAlt() =
  interface ISerialiser with
    member __.Serialise _ =
     System.Threading.Thread.Sleep(20)

type Serialisers() =
  let fast, fastAlt, slow =
    FastSerialiser() :> ISerialiser,
    FastSerialiserAlt() :> ISerialiser,
    MySlowSerialiser() :> ISerialiser

  [<Benchmark>]
  member __.FastSerialiserAlt() = fastAlt.Serialise "Hello world"

  [<Benchmark>]
  member __.SlowSerialiser() = slow.Serialise "Hello world"

  [<Benchmark(Baseline = true)>]
  member __.FastSerialiser() = fast.Serialise "Hello world"

[<Tests>]
let tests =
  testList "performance tests" [
    test "three serialisers" {
      benchmark<Serialisers> benchmarkConfig (fun _ -> null) |> ignore
    }
  ]
```

--------------------------------

### Basic Assertions with Fluent API

Source: https://github.com/haf/expecto/blob/main/README.md

Demonstrates using the fluent API with Expect.equal for basic value assertions. This pattern is useful for chaining multiple assertions on a computed value.

```F#
open Expecto
open Expecto.Flip

let compute (multiplier: int) = 42 * multiplier

test "yup yup" {
  compute 1
    |> Expect.equal "x1 = 42" 42

  compute 2
    |> Expect.equal "x2 = 82" 84
}
|> runTestsWithCLIArgs [] [||]
```

--------------------------------

### Running All Tests via CLI

Source: https://github.com/haf/expecto/blob/main/_autodocs/README.md

Command to execute all tests defined in the project using the .NET CLI. Assumes tests are discoverable.

```bash
dotnet run
```