tree: 63a8da353b2619231bd5f9ec162eb10714066f51 [path history] [tgz]
  1. BUILD.gn
  2. OWNERS
  3. README.md
  4. examples/
  5. fidl/
  6. lib/
  7. named-timer/
  8. svc/
src/lib/fake-clock/README.md

Fake-clock

A system enabling a test component to manipulate monotonic time for components under test.

Fake-clock consists of a library and service component.

The service component maintains a fake monotonic time, which may be accessed through the fuchsia.testing.FakeClock protocol and may be controlled through the fuchsia.testing.FakeClockControl protocol.

The library overrides syscalls defined in the vDSO that interact with monotonic time or have a built in deadline. The overrides route time-based waits and signals to the service component via the fuchsia.testing.FakeClock protocol.

In addition, the named-timer crate allows an author to annotate critical deadlines in a component with names. When linked against the fake-clock library, the deadline set and expired events are reported to the fake-clock service. A test author may register interest in these events to stop time when these critical points are reached.

Use

A test that wishes to use fake-clock must correctly link the library to each component in the test and route the fuchsia.testing.* protocols.

Add the service component as a dependency in the test package.

fuchsia_test_package("my-integ-test") {
  test_components = [ "integ-test-component" ]
  deps = [
    ":component_with_fake_time",
    "//src/lib/fake-clock/svc",
  ]
}

Link the library against each binary. Since the library is only available to test targets, create a new version of the binary that depends on “//src/lib/fake-clock/lib”.

# Rust binary
rustc_binary("bin_with_fake_time") {
    ...
    testonly = true
    non_rust_deps = [ "//src/lib/fake-clock/lib" ]
}

# C++ binary
executable("bin_with_fake_time") {
    ...
    testonly = true
    deps = [
        ...
        "//src/lib/fake-clock/lib"
    ]
}

# Component with fake time
fuchsia_component("component_with_fake_time") {
    testonly = true
    component_name = "component_with_fake_time"
    manifest "meta/component_with_fake_time.cmx"
    deps = [":bin_with_fake_time"]
}

Include the fake-clock shard in the manifest for each component with fake time.

    ...
    "include": [
        "//src/lib/fake-clock/lib/client.shard.cmx"
    ],

Add the fuchsia.testing.FakeClockControl protocol to the test component's manifest.

    ...
    "sandbox": {
        "services": [
            "fuchsia.testing.FakeClockControl"
        ]
    }

The test may then connect to fuchsia.testing.FakeClockControl to control monotonic time.

See the examples directory for example setups.