From 90f3b558c8496194d9b2bbaedda3910d43a904f7 Mon Sep 17 00:00:00 2001 From: sengjea Date: Tue, 3 Nov 2026 10:58:44 +0000 Subject: [PATCH] Add RunWithOverrides, to replace the task which provides a key Tasks often create things for themselves, such as clients of other services, which leaves a graph with no way to give it fakes in a test. RunWithOverrides runs a graph with the tasks providing the keys of some bindings replaced by them. The replaced tasks do not run. It does this by making a graph like the original, in which each task that is replaced is a task with no dependencies which provides the overrides, and running that. The engine is not changed, nor are Graph.Run and Graph.Check. An input for a key which a task provides is still a duplicate binding, so a key is only ever replaced on purpose. Overriding a key no task provides, or only some of the keys a task provides, is an error, as is overriding a key twice or a key which is also an input. An absent override replaces the task with a failure. Overrides are part of the Binder returned, and inputs only a replaced task needed are no longer required. CheckWithOverrides validates them without running the graph. A replacing task has no dependencies, so the tasks which fed the task it replaces have nothing to signal, and inputs which only a replaced task needed are not required. Those tasks still run. Overrider holds one set of overrides for code which runs several graphs, such as an operator with a graph to create and one to delete: each graph takes the overrides for the keys it provides, and Check finds any which are for none of them. taskgraphtest's Test and Suite take Overrides, those of a Test replacing those of its Suite for the same key. --- README.md | 41 +++ override.go | 144 ++++++++ override_plan.go | 98 ++++++ override_test.go | 497 ++++++++++++++++++++++++++++ taskgraphtest/taskgraphtest.go | 41 ++- taskgraphtest/taskgraphtest_test.go | 162 +++++++++ 6 files changed, 982 insertions(+), 1 deletion(-) create mode 100644 override.go create mode 100644 override_plan.go create mode 100644 override_test.go create mode 100644 taskgraphtest/taskgraphtest_test.go diff --git a/README.md b/README.md index f3fe750..1815068 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,47 @@ result, execution of the graph is performed as a parallelised breadth first sear This package contains some creative APIs which work around limitations in Golang generics; chief of these is the `ID` type used in place of slices of keys because Golang slices are invariant. +## Overriding tasks + +A graph's tasks often create things for themselves: clients of other services, say. That makes a +whole graph hard to test, as there is no way to give it a fake client. `RunWithOverrides` replaces the +task which provides a key: + +```go +tg.RunWithOverrides(ctx, graph, inputs, []tg.Binding{keyClient.Bind(fakeClient)}) +``` + +The task providing `keyClient` is not run, and the tasks which depend on it see the fake. This makes +a graph's dependencies a matter of which keys its tasks provide: anything which a test may want to +replace should be a key of its own. + +It is meant for tests: `Graph.Run` has no way to replace tasks, so code which runs a graph and needs to +be tested can take a function for running graphs, and be handed `Overrider.Run` by its tests. + +* An input for a key which a task provides is still an error, so a key is only ever replaced on + purpose. The same goes for overriding one key twice, or overriding a key which is also an input. +* If a task provides several keys they must all be overridden, or none (`ErrPartialOverride`). + Otherwise the task would still have to run, with all of its effects, with some of its results + thrown away. +* Overriding a key which no task provides is an error (`ErrUnknownOverride`), which catches + overrides left behind by a task which has since been renamed or removed. `CheckWithOverrides` + finds these without running the graph. +* The override may be absent: `keyClient.BindError(err)` replaces the task with a failure, to see how + the tasks which depend on it cope. +* The overrides are included in the `Binder` returned, as the results of the tasks they replace would + have been. +* Inputs which only a replaced task needed are not required. +* Tasks which only produced inputs for a replaced task still run, as the graph can't know that its + caller doesn't want their results. +* Overrides apply to the graph they are given. A graph run as a task with `AsTask` is replaced as a + whole, by overriding every key it exposes, but its tasks can't be overridden individually. +* An `Overrider` holds one set of overrides for something which runs several graphs, such as an + operator with a graph to create and a graph to delete. Each graph is run with the overrides for the + keys it provides, and `Overrider.Check` makes sure that every override is for some graph. + +`taskgraphtest.Test` and `taskgraphtest.Suite` take `Overrides`, those of a `Test` replacing those +of its `Suite` for the same key. + ## Limitations and sharp edges * Taskgraph has no deadlock detection. In theory the fact that the graph is acyclic should prevent diff --git a/override.go b/override.go new file mode 100644 index 0000000..d4dd4fb --- /dev/null +++ b/override.go @@ -0,0 +1,144 @@ +package taskgraph + +import ( + "context" + "errors" + "fmt" + "sort" + "strings" +) + +var ( + // ErrUnknownOverride is returned by RunWithOverrides and CheckWithOverrides if an override is + // given for a key which no task in the graph provides. This is almost always a stale override, + // left over from a task which has since been renamed or removed. + ErrUnknownOverride = errors.New("override of a key which no task provides") + + // ErrPartialOverride is returned by RunWithOverrides and CheckWithOverrides if overrides cover + // some, but not all, of the keys which a task provides. The task would still have to run, with + // all of its effects, only to have some of its results discarded, which is very unlikely to be + // what was intended. Override all of a task's keys, or none of them. + ErrPartialOverride = errors.New("override of only some of the keys which a task provides") +) + +// RunWithOverrides runs the graph, as Graph.Run does with the inputs, with the tasks which provide +// the keys of the overrides replaced by them. It is the way to substitute what the tasks of a graph +// would otherwise create for themselves, such as clients of other services, in a test: +// +// taskgraph.RunWithOverrides(ctx, graph, inputs, []taskgraph.Binding{keyClient.Bind(fakeClient)}) +// +// The task providing the key is not run. If the task provides other keys as well, they must all be +// overridden too (ErrPartialOverride), so that the real task's effects can never happen unnoticed. +// Tasks which have no other purpose than to produce the inputs of a task which is not run are still +// run, as are tasks which depend on the overridden key; they see the override as if the task which +// it replaces had produced it. The overrides are included in the Binder returned, as the replaced +// tasks' results would have been, and inputs which only a replaced task needed are not required. +// +// An override may be absent, which replaces the task with a failure: +// +// keyClient.BindError(errUnreachable) +// +// Overriding a key which no task provides is an error (ErrUnknownOverride), as is overriding the same +// key twice, or overriding a key which is also given as an input. An input for a key which a task +// provides is still an error (ErrDuplicateBinding), so a key can only ever be replaced on purpose. +// +// Overrides apply to the graph's own tasks. A graph run as a task with Graph.AsTask is replaced as a +// whole, by overriding every key it exposes, but its tasks can't be overridden individually. +// +// This is a function, not a method of Graph, so that the Graph interface, which other code may +// implement, is not changed. It only works on graphs made by New. +func RunWithOverrides( + ctx context.Context, + g Graph, + inputs, overrides []Binding, +) (Binder, error) { + graph, err := asGraph(g) + if err != nil { + return nil, err + } + replaced, err := graph.withOverrides(inputs, overrides) + if err != nil { + return nil, err + } + return replaced.Run(ctx, inputs...) +} + +// CheckWithOverrides is Graph.Check, with the overrides RunWithOverrides would be given: it finds +// unknown, duplicated and partial overrides, and which inputs are still needed, without running +// anything. +func CheckWithOverrides(g Graph, inputs, overrides []Binding) error { + graph, err := asGraph(g) + if err != nil { + return err + } + replaced, err := graph.withOverrides(inputs, overrides) + if err != nil { + return err + } + return replaced.Check(inputs...) +} + +// An Overrider runs graphs with one set of overrides. It is for something which runs several graphs, +// such as an operator with a graph to create and one to delete, and which can only be given one set: +// each graph is run with those of the overrides which are for keys it provides, and Check makes sure +// that every override is for some graph. Run does not report an override which is for none of the +// graphs, as it can't tell that from one for another graph, so Check is how to find a stale one. +type Overrider struct { + overrides []Binding +} + +// NewOverrider returns an Overrider with the overrides. +func NewOverrider(overrides ...Binding) *Overrider { + return &Overrider{overrides: overrides} +} + +// Run runs the graph with the inputs, and those of the Overrider's overrides which are for keys the +// graph provides. Its signature is that of a function for running a graph, so it can be handed to +// code which runs graphs. +func (o *Overrider) Run(ctx context.Context, g Graph, inputs ...Binding) (Binder, error) { + graph, err := asGraph(g) + if err != nil { + return nil, err + } + var own []Binding + for _, override := range o.overrides { + if graph.allProvided.Contains(override.ID()) { + own = append(own, override) + } + } + return RunWithOverrides(ctx, g, inputs, own) +} + +// Check returns an error if any of the overrides is for a key which none of the graphs provide, which +// is nearly always one left behind by a task which has been renamed or removed. +func (o *Overrider) Check(graphs ...Graph) error { + var unknown []string + for _, override := range o.overrides { + provided := false + for _, g := range graphs { + if graph, err := asGraph(g); err == nil && graph.allProvided.Contains(override.ID()) { + provided = true + break + } + } + if !provided { + unknown = append(unknown, override.ID().String()) + } + } + if len(unknown) > 0 { + sort.Strings(unknown) + return fmt.Errorf("%w: %s", ErrUnknownOverride, strings.Join(unknown, ", ")) + } + return nil +} + +func asGraph(g Graph) (*graph, error) { + graph, ok := g.(*graph) + if !ok { + return nil, fmt.Errorf( + "overrides can only be applied to a Graph made by taskgraph.New, not %T", + g, + ) + } + return graph, nil +} diff --git a/override_plan.go b/override_plan.go new file mode 100644 index 0000000..1e8b04d --- /dev/null +++ b/override_plan.go @@ -0,0 +1,98 @@ +package taskgraph + +import ( + "context" + "fmt" + "sort" + "strings" + + set "github.com/deckarep/golang-set/v2" +) + +// withOverrides returns a graph like g, but with each task whose keys are all overridden replaced by a +// task which provides the overriding bindings. The graph is g itself if there are no overrides. +// +// A replacement has no dependencies, so the tasks which fed the task it replaces have nothing to +// signal, and inputs which only the replaced task needed are not required. Those tasks still run, as +// the graph can't know that its caller doesn't want their results. +// +// An override is an error if it is for a key which is also an input or is overridden twice, as that +// is a mistake in which one is meant; if no task provides its key, which is nearly always a task +// which has been renamed or removed; or if it is for only some of the keys which a task provides, +// as the task would then have to run for the others and its effects could not be ruled out. +func (g *graph) withOverrides(inputs, overrides []Binding) (*graph, error) { + if len(overrides) == 0 { + return g, nil + } + + given := set.NewSet[ID]() + for _, input := range inputs { + given.Add(input.ID()) + } + overriddenBy := map[ID]Binding{} + for _, o := range overrides { + if given.Contains(o.ID()) { + return nil, wrapStackErrorf( + "override of a key which is also an input: %w: %q", ErrDuplicateBinding, o.ID()) + } + if _, twice := overriddenBy[o.ID()]; twice { + return nil, wrapStackErrorf("key overridden twice: %w: %q", ErrDuplicateBinding, o.ID()) + } + overriddenBy[o.ID()] = o + } + + var unknown []string + for id := range overriddenBy { + if !g.allProvided.Contains(id) { + unknown = append(unknown, id.String()) + } + } + if len(unknown) > 0 { + sort.Strings(unknown) + return nil, wrapStackErrorf("%w: %s", ErrUnknownOverride, strings.Join(unknown, ", ")) + } + + var tasks []TaskSet + var partial []string + for _, t := range g.tasks { + var covered []Binding + var uncovered []string + for _, id := range t.Provides() { + if o, ok := overriddenBy[id]; ok { + covered = append(covered, o) + } else { + uncovered = append(uncovered, id.String()) + } + } + switch { + case len(covered) == 0: + tasks = append(tasks, t) + case len(uncovered) == 0: + tasks = append(tasks, replacement(t, covered)) + default: + partial = append(partial, fmt.Sprintf( + "task %s also provides [%s], which are not overridden", + t.Name(), strings.Join(uncovered, ", "))) + } + } + if len(partial) > 0 { + sort.Strings(partial) + return nil, wrapStackErrorf("%w: %s", ErrPartialOverride, strings.Join(partial, "; ")) + } + + replaced, err := New(g.name, WithTasks(tasks...), WithTracer(g.tracer), WithLogger(g.logger)) + if err != nil { + return nil, err + } + return replaced.(*graph), nil +} + +// replacement is a task in place of t which provides the overrides for all of the keys of t. +func replacement(t Task, overrides []Binding) Task { + return NewTask( + t.Name()+" (overridden)", + func(context.Context, Binder) ([]Binding, error) { return overrides, nil }, + nil, + t.Provides(), + ) +} diff --git a/override_test.go b/override_test.go new file mode 100644 index 0000000..aae5ac2 --- /dev/null +++ b/override_test.go @@ -0,0 +1,497 @@ +package taskgraph_test + +import ( + "context" + "errors" + "sync/atomic" + "testing" + "time" + + tg "github.com/thought-machine/taskgraph" + tgt "github.com/thought-machine/taskgraph/taskgraphtest" +) + +// overrideFixture is a small graph, in -> A -> B, whose tasks count how often they run: +// +// A: a = in * 2 +// B: b = a + 1 +type overrideFixture struct { + keyIn, keyA, keyB tg.Key[int] + runsA, runsB atomic.Int32 + graph tg.Graph +} + +func newOverrideFixture(t *testing.T) *overrideFixture { + t.Helper() + f := &overrideFixture{ + keyIn: tg.NewKey[int]("in"), + keyA: tg.NewKey[int]("a"), + keyB: tg.NewKey[int]("b"), + } + f.graph = tgt.Must[tg.Graph](t)(tg.New("override_graph", tg.WithTasks( + tg.SimpleTask1[int, int]("A", f.keyA, func(_ context.Context, in int) (int, error) { + f.runsA.Add(1) + return in * 2, nil + }, f.keyIn), + tg.SimpleTask1[int, int]("B", f.keyB, func(_ context.Context, a int) (int, error) { + f.runsB.Add(1) + return a + 1, nil + }, f.keyA), + ))) + return f +} + +func (f *overrideFixture) run( + t *testing.T, + inputs []tg.Binding, + overrides ...tg.Binding, +) tg.Binder { + t.Helper() + result, err := tg.RunWithOverrides(testContext(t), f.graph, inputs, overrides) + if err != nil { + t.Fatalf("Run() failed: %v", err) + } + return result +} + +// testContext returns a context which ends soon, so that a graph which wrongly waits for something +// which will never happen fails the test, rather than hanging it. +func testContext(t *testing.T) context.Context { + t.Helper() + ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + t.Cleanup(cancel) + return ctx +} + +func mustGet[T any](t *testing.T, key tg.ReadOnlyKey[T], b tg.Binder) T { + t.Helper() + got, err := key.Get(b) + if err != nil { + t.Fatalf("getting %s: %v", key.ID(), err) + } + return got +} + +func TestOverride_WithoutOverrideTasksRun(t *testing.T) { + f := newOverrideFixture(t) + result := f.run(t, []tg.Binding{f.keyIn.Bind(1)}) + + if got, want := mustGet(t, f.keyB, result), 3; got != want { + t.Errorf("b = %d; want %d", got, want) + } + if f.runsA.Load() != 1 || f.runsB.Load() != 1 { + t.Errorf("tasks ran A %d times, B %d times; want once each", f.runsA.Load(), f.runsB.Load()) + } +} + +func TestOverride_ReplacesTheTaskWhichProvidesTheKey(t *testing.T) { + f := newOverrideFixture(t) + result := f.run(t, []tg.Binding{f.keyIn.Bind(1)}, f.keyA.Bind(100)) + + if f.runsA.Load() != 0 { + t.Errorf("A ran %d times; want it replaced", f.runsA.Load()) + } + if got, want := mustGet(t, f.keyB, result), 101; got != want { + t.Errorf("b = %d; want %d, from the override", got, want) + } + // The override takes the place of the result the task would have produced. + if got, want := mustGet(t, f.keyA, result), 100; got != want { + t.Errorf("a in the result = %d; want the override, %d", got, want) + } +} + +func TestOverride_GraphCanBeRunAgainWithDifferentOverrides(t *testing.T) { + f := newOverrideFixture(t) + + if got, want := mustGet( + t, + f.keyB, + f.run(t, []tg.Binding{f.keyIn.Bind(1)}, f.keyA.Bind(10)), + ), 11; got != want { + t.Errorf("first run: b = %d; want %d", got, want) + } + if got, want := mustGet(t, f.keyB, f.run(t, []tg.Binding{f.keyIn.Bind(1)})), 3; got != want { + t.Errorf("second run, without an override: b = %d; want %d", got, want) + } + if got, want := mustGet( + t, + f.keyB, + f.run(t, []tg.Binding{f.keyIn.Bind(1)}, f.keyA.Bind(20)), + ), 21; got != want { + t.Errorf("third run: b = %d; want %d", got, want) + } + if f.runsA.Load() != 1 { + t.Errorf( + "A ran %d times over the three runs; want once, in the one without an override", + f.runsA.Load(), + ) + } +} + +func TestOverride_AbsentOverrideFailsTheTask(t *testing.T) { + errBoom := errors.New("boom") + keyIn, keyA, keyB := tg.NewKey[int]("in"), tg.NewKey[int]("a"), tg.NewKey[int]("b") + var runsA atomic.Int32 + g := tgt.Must[tg.Graph](t)(tg.New("absent_override", tg.WithTasks( + tg.SimpleTask1[int, int]("A", keyA, func(_ context.Context, in int) (int, error) { + runsA.Add(1) + return in, nil + }, keyIn), + // Takes the absence of a in its stride, as a task which can cope with a missing dependency does. + tg.NewTask("B", func(_ context.Context, b tg.Binder) ([]tg.Binding, error) { + if _, err := keyA.Get(b); err != nil { + return []tg.Binding{keyB.Bind(-1)}, nil + } + return []tg.Binding{keyB.Bind(1)}, nil + }, []tg.ID{keyA.ID()}, []tg.ID{keyB.ID()}), + ))) + + result, err := tg.RunWithOverrides( + testContext(t), + g, + []tg.Binding{keyIn.Bind(1)}, + []tg.Binding{keyA.BindError(errBoom)}, + ) + if err != nil { + t.Fatalf("Run() failed: %v", err) + } + if runsA.Load() != 0 { + t.Errorf("A ran %d times; want it replaced by the failure", runsA.Load()) + } + if got := mustGet(t, keyB, result); got != -1 { + t.Errorf("b = %d; want -1, as B saw a absent", got) + } + tgt.ExpectAbsentError(t, result, keyA, errBoom) +} + +func TestOverride_ConditionalTaskIsReplacedWhateverItsCondition(t *testing.T) { + for _, flag := range []bool{true, false} { + keyFlag, keyT, keyOut := tg.NewKey[bool]("flag"), tg.NewKey[int]("t"), tg.NewKey[int]("out") + var runsT atomic.Int32 + g := tgt.Must[tg.Graph](t)(tg.New("conditional_override", tg.WithTasks( + tg.Conditional{ + Wrapped: tg.SimpleTask("T", keyT, func(context.Context, tg.Binder) (int, error) { + runsT.Add(1) + return 1, nil + }), + Condition: tg.ConditionAnd{keyFlag}, + }.Locate(), + tg.SimpleTask1[int, int]("Out", keyOut, func(_ context.Context, v int) (int, error) { + return v * 10, nil + }, keyT), + ))) + + result, err := tg.RunWithOverrides( + testContext(t), + g, + []tg.Binding{keyFlag.Bind(flag)}, + []tg.Binding{keyT.Bind(7)}, + ) + if err != nil { + t.Fatalf("flag=%v: Run() failed: %v", flag, err) + } + if runsT.Load() != 0 { + t.Errorf("flag=%v: T ran %d times; want it replaced", flag, runsT.Load()) + } + if got, want := mustGet(t, keyOut, result), 70; got != want { + t.Errorf("flag=%v: out = %d; want %d", flag, got, want) + } + } +} + +func TestOverride_TasksWhichFedAReplacedTaskStillRunAndDoNotBlock(t *testing.T) { + // This documents a limitation: the graph can't know which results its caller wants, so it can't + // tell that nothing needs what only the replaced task consumed. + f := newOverrideFixture(t) + keyU, runsU := tg.NewKey[int]("u"), atomic.Int32{} + g := tgt.Must[tg.Graph](t)(tg.New("upstream_still_runs", tg.WithTasks( + tg.SimpleTask1[int, int]("U", keyU, func(_ context.Context, in int) (int, error) { + runsU.Add(1) + return in, nil + }, f.keyIn), + tg.SimpleTask1[int, int]("A", f.keyA, func(_ context.Context, u int) (int, error) { + return u * 2, nil + }, keyU), + ))) + + if _, err := tg.RunWithOverrides( + testContext(t), + g, + []tg.Binding{f.keyIn.Bind(1)}, + []tg.Binding{f.keyA.Bind(5)}, + ); err != nil { + t.Fatalf("Run() failed: %v", err) + } + if runsU.Load() != 1 { + t.Errorf("U ran %d times; want once", runsU.Load()) + } +} + +func TestOverride_InputsOnlyAReplacedTaskNeededAreNotRequired(t *testing.T) { + keyOnlyForA, keyA, keyOut := tg.NewKey[int]( + "only_for_a", + ), tg.NewKey[int]( + "a", + ), tg.NewKey[int]( + "out", + ) + g := tgt.Must[tg.Graph](t)(tg.New("needed_inputs", tg.WithTasks( + tg.SimpleTask1[int, int]( + "A", + keyA, + func(_ context.Context, v int) (int, error) { return v, nil }, + keyOnlyForA, + ), + tg.SimpleTask1[int, int]( + "Out", + keyOut, + func(_ context.Context, a int) (int, error) { return a + 1, nil }, + keyA, + ), + ))) + + if _, err := tg.RunWithOverrides( + testContext(t), + g, + nil, + nil, + ); !errors.Is( + err, + tg.ErrMissingInputs, + ) { + t.Errorf("without the override: got %v; want ErrMissingInputs", err) + } + result, err := tg.RunWithOverrides(testContext(t), g, nil, []tg.Binding{keyA.Bind(4)}) + if err != nil { + t.Fatalf("with the override: Run() failed: %v", err) + } + if got, want := mustGet(t, keyOut, result), 5; got != want { + t.Errorf("out = %d; want %d", got, want) + } +} + +func TestOverride_TasksDependingOnReplacedAndOrdinaryKeysDoNotWaitForeverOrDeadlock(t *testing.T) { + keyIn, keyA, keyP, keyBoth, keyOnlyA := tg.NewKey[int]( + "in", + ), tg.NewKey[int]( + "a", + ), tg.NewKey[int]( + "p", + ), + tg.NewKey[int]( + "both", + ), tg.NewKey[int]( + "only_a", + ) + g := tgt.Must[tg.Graph](t)(tg.New("mixed_dependents", tg.WithTasks( + tg.SimpleTask1[int, int]( + "A", + keyA, + func(_ context.Context, v int) (int, error) { return v, nil }, + keyIn, + ), + tg.SimpleTask1[int, int]("P", keyP, func(_ context.Context, v int) (int, error) { + time.Sleep(20 * time.Millisecond) + return v * 100, nil + }, keyIn), + tg.SimpleTask2[int, int, int]( + "Both", + keyBoth, + func(_ context.Context, a, p int) (int, error) { + return a + p, nil + }, + keyA, + keyP, + ), + tg.SimpleTask1[int, int]( + "OnlyA", + keyOnlyA, + func(_ context.Context, a int) (int, error) { return a, nil }, + keyA, + ), + ))) + + result, err := tg.RunWithOverrides( + testContext(t), + g, + []tg.Binding{keyIn.Bind(1)}, + []tg.Binding{keyA.Bind(7)}, + ) + if err != nil { + t.Fatalf("Run() failed: %v", err) + } + if got, want := mustGet(t, keyBoth, result), 107; got != want { + t.Errorf("both = %d; want %d", got, want) + } + if got, want := mustGet(t, keyOnlyA, result), 7; got != want { + t.Errorf("only_a = %d; want %d", got, want) + } +} + +func TestOverride_Errors(t *testing.T) { + keyIn, keyA, keyM1, keyM2, keyZ := tg.NewKey[int]( + "in", + ), tg.NewKey[int]( + "a", + ), tg.NewKey[int]( + "m1", + ), + tg.NewKey[int]( + "m2", + ), tg.NewKey[int]( + "z", + ) + var runsM atomic.Int32 + g := tgt.Must[tg.Graph](t)(tg.New("override_errors", tg.WithTasks( + tg.SimpleTask1[int, int]( + "A", + keyA, + func(_ context.Context, v int) (int, error) { return v, nil }, + keyIn, + ), + tg.NewTask("M", func(_ context.Context, _ tg.Binder) ([]tg.Binding, error) { + runsM.Add(1) + return []tg.Binding{keyM1.Bind(1), keyM2.Bind(2)}, nil + }, nil, []tg.ID{keyM1.ID(), keyM2.ID()}), + ))) + + for _, tc := range []struct { + description string + inputs []tg.Binding + overrides []tg.Binding + wantError error + // Whether the problem is found before anything runs, which is true of everything but a plain + // input for a key which a task provides, which is only found when that task stores its result. + foundBeforeRunning bool + }{ + { + description: "a key which no task provides", + inputs: []tg.Binding{keyIn.Bind(1)}, + overrides: []tg.Binding{keyZ.Bind(1)}, + wantError: tg.ErrUnknownOverride, + foundBeforeRunning: true, + }, + { + description: "an input, not an override, for a key which a task provides", + inputs: []tg.Binding{keyIn.Bind(1), keyA.Bind(5)}, + wantError: tg.ErrDuplicateBinding, + }, + { + description: "the same key overridden twice", + inputs: []tg.Binding{keyIn.Bind(1)}, + overrides: []tg.Binding{keyA.Bind(1), keyA.Bind(2)}, + wantError: tg.ErrDuplicateBinding, + foundBeforeRunning: true, + }, + { + description: "a key which is also an ordinary input", + inputs: []tg.Binding{keyIn.Bind(1), keyA.Bind(1)}, + overrides: []tg.Binding{keyA.Bind(2)}, + wantError: tg.ErrDuplicateBinding, + foundBeforeRunning: true, + }, + { + description: "only some of the keys which a task provides", + inputs: []tg.Binding{keyIn.Bind(1)}, + overrides: []tg.Binding{keyM1.Bind(1)}, + wantError: tg.ErrPartialOverride, + foundBeforeRunning: true, + }, + } { + t.Run(tc.description, func(t *testing.T) { + runsM.Store(0) + if _, err := tg.RunWithOverrides( + testContext(t), + g, + tc.inputs, + tc.overrides, + ); !errors.Is( + err, + tc.wantError, + ) { + t.Errorf("Run(): got %v; want %v", err, tc.wantError) + } + if tc.foundBeforeRunning { + if runsM.Load() != 0 { + t.Errorf( + "M ran %d times; want nothing to run, as this is rejected first", + runsM.Load(), + ) + } + if err := tg.CheckWithOverrides( + g, + tc.inputs, + tc.overrides, + ); !errors.Is( + err, + tc.wantError, + ) { + t.Errorf("Check(): got %v; want %v", err, tc.wantError) + } + } + }) + } + + t.Run("all of the keys which a task provides", func(t *testing.T) { + runsM.Store(0) + inputs := []tg.Binding{keyIn.Bind(1)} + overrides := []tg.Binding{keyM1.Bind(10), keyM2.Bind(20)} + if err := tg.CheckWithOverrides(g, inputs, overrides); err != nil { + t.Fatalf("Check(): %v", err) + } + result, err := tg.RunWithOverrides(testContext(t), g, inputs, overrides) + if err != nil { + t.Fatalf("Run(): %v", err) + } + if runsM.Load() != 0 { + t.Errorf("M ran %d times; want it replaced", runsM.Load()) + } + if got := mustGet(t, keyM2, result); got != 20 { + t.Errorf("m2 = %d; want 20", got) + } + }) +} + +func TestOverride_GraphRunAsATaskIsReplacedAsAWhole(t *testing.T) { + keyIn, keyX, keyY := tg.NewKey[int]("in"), tg.NewKey[int]("x"), tg.NewKey[int]("y") + var runsInner atomic.Int32 + inner := tgt.Must[tg.Graph](t)(tg.New("inner", tg.WithTasks( + tg.NewTask("XY", func(_ context.Context, b tg.Binder) ([]tg.Binding, error) { + runsInner.Add(1) + in := mustGet(t, keyIn, b) + return []tg.Binding{keyX.Bind(in), keyY.Bind(in * 2)}, nil + }, []tg.ID{keyIn.ID()}, []tg.ID{keyX.ID(), keyY.ID()}), + ))) + asTask := tgt.Must[tg.Task](t)(inner.AsTask(keyX.ID(), keyY.ID())) + outer := tgt.Must[tg.Graph](t)(tg.New("outer", tg.WithTasks(asTask))) + + if _, err := tg.RunWithOverrides( + testContext(t), + outer, + []tg.Binding{keyIn.Bind(1)}, + []tg.Binding{keyX.Bind(9)}, + ); !errors.Is( + err, + tg.ErrPartialOverride, + ) { + t.Errorf( + "overriding one of the keys the task exposes: got %v; want ErrPartialOverride", + err, + ) + } + result, err := tg.RunWithOverrides( + testContext(t), + outer, + []tg.Binding{keyIn.Bind(1)}, + []tg.Binding{keyX.Bind(9), keyY.Bind(8)}, + ) + if err != nil { + t.Fatalf("overriding both: Run() failed: %v", err) + } + if runsInner.Load() != 0 { + t.Errorf("the inner graph ran %d times; want it replaced", runsInner.Load()) + } + if got := mustGet(t, keyY, result); got != 8 { + t.Errorf("y = %d; want 8", got) + } +} diff --git a/taskgraphtest/taskgraphtest.go b/taskgraphtest/taskgraphtest.go index b783131..98f9b17 100644 --- a/taskgraphtest/taskgraphtest.go +++ b/taskgraphtest/taskgraphtest.go @@ -263,6 +263,14 @@ type Test struct { // Inputs defines the inputs passed to the graph for the test. Inputs []tg.Binding + // Overrides defines bindings which replace the tasks providing their keys, as with + // tg.RunWithOverrides; the replaced tasks are not run. Overrides given by the Suite + // are applied as well, those given here replacing them for the same key. + // + // The overrides are part of the result, as the replaced tasks' results would have been, so + // CheckExcessBindings counts them among the bindings to be wanted. + Overrides []tg.Binding + // WantError defines the expected error returned from the Graph's execution (note that the test // will always fail if Graph setup/configuration fails). Compared using errors.Is. WantError error @@ -314,7 +322,13 @@ func (test Test) Run(t *testing.T) { ctx, cancel := context.WithTimeout(context.Background(), test.Timeout) defer cancel() - result, err := test.Graph.Run(ctx, test.Inputs...) + var result tg.Binder + var err error + if len(test.Overrides) == 0 { + result, err = test.Graph.Run(ctx, test.Inputs...) + } else { + result, err = tg.RunWithOverrides(ctx, test.Graph, test.Inputs, test.Overrides) + } if !errors.Is(err, test.WantError) { t.Fatalf("Difference in error from Graph.Run(): got %v; want %v", err, test.WantError) @@ -354,6 +368,11 @@ type Suite struct { // the set is expected to contain a single element. Task tg.TaskSet + // Overrides defines bindings which replace the tasks providing their keys in every test of the + // suite (see Test.Overrides). A test which overrides the same key itself uses its own binding in + // place of the suite's. + Overrides []tg.Binding + // Tests defines the individual tests to be run. Tests []Test @@ -382,10 +401,30 @@ func (s Suite) Run(t *testing.T) { if test.Timeout <= 0 { test.Timeout = s.Timeout } + test.Overrides = mergeOverrides(s.Overrides, test.Overrides) t.Run(test.Description, test.Run) } } +// mergeOverrides returns the overrides of a suite and of one of its tests together, those of the test +// replacing those of the suite which are for the same key. +func mergeOverrides(suite, test []tg.Binding) []tg.Binding { + if len(suite) == 0 { + return test + } + overridden := set.NewSet[tg.ID]() + for _, b := range test { + overridden.Add(b.ID()) + } + merged := append([]tg.Binding{}, test...) + for _, b := range suite { + if !overridden.Contains(b.ID()) { + merged = append(merged, b) + } + } + return merged +} + // DummyTaskFunc returns a function suitable for passing to taskgraph.NewTask which returns the // given bindings. func DummyTaskFunc(bindings ...tg.Binding) func(context.Context, tg.Binder) ([]tg.Binding, error) { diff --git a/taskgraphtest/taskgraphtest_test.go b/taskgraphtest/taskgraphtest_test.go new file mode 100644 index 0000000..5d99772 --- /dev/null +++ b/taskgraphtest/taskgraphtest_test.go @@ -0,0 +1,162 @@ +package taskgraphtest_test + +import ( + "context" + "errors" + "sync/atomic" + "testing" + + tg "github.com/thought-machine/taskgraph" + tgt "github.com/thought-machine/taskgraph/taskgraphtest" +) + +func TestOverrides(t *testing.T) { + keyIn, keyA, keyB := tg.NewKey[int]("in"), tg.NewKey[int]("a"), tg.NewKey[int]("b") + var runsA atomic.Int32 + graph := tgt.Must[tg.Graph](t)(tg.New("overrides", tg.WithTasks( + tg.SimpleTask1[int, int]("A", keyA, func(_ context.Context, in int) (int, error) { + runsA.Add(1) + return in * 2, nil + }, keyIn), + tg.SimpleTask1[int, int]("B", keyB, func(_ context.Context, a int) (int, error) { + return a + 1, nil + }, keyA), + ))) + + tgt.Suite{ + Graph: graph, + Overrides: []tg.Binding{keyA.Bind(10)}, + Tests: []tgt.Test{ + { + Description: "a suite's overrides apply to its tests", + Inputs: []tg.Binding{keyIn.Bind(1)}, + WantBindings: []tgt.BindingMatcher{tgt.Match(keyB.Bind(11))}, + }, + { + Description: "a test's override replaces the suite's for the same key", + Inputs: []tg.Binding{keyIn.Bind(1)}, + Overrides: []tg.Binding{keyA.Bind(20)}, + WantBindings: []tgt.BindingMatcher{tgt.Match(keyB.Bind(21))}, + }, + { + Description: "overrides are part of the result", + Inputs: []tg.Binding{keyIn.Bind(1)}, + WantBindings: []tgt.BindingMatcher{ + tgt.Match(keyA.Bind(10)), + tgt.Match(keyB.Bind(11)), + }, + }, + { + Description: "excess bindings includes them", + Inputs: []tg.Binding{keyIn.Bind(1)}, + WantBindings: []tgt.BindingMatcher{ + tgt.Match(keyA.Bind(10)), + tgt.Match(keyB.Bind(11)), + }, + CheckExcessBindings: true, + }, + { + Description: "an absent override makes the task fail", + Inputs: []tg.Binding{keyIn.Bind(1)}, + Overrides: []tg.Binding{keyA.BindAbsent()}, + WantBindings: []tgt.BindingMatcher{tgt.Match(keyA.BindAbsent())}, + WantError: tg.ErrIsAbsent, + }, + }, + }.Run(t) + + if runsA.Load() != 0 { + t.Errorf("A ran %d times; want it replaced in every test", runsA.Load()) + } + + // A test which isn't part of a suite can override too. + tgt.Test{ + Graph: graph, + Inputs: []tg.Binding{keyIn.Bind(1)}, + Overrides: []tg.Binding{keyA.Bind(5)}, + WantBindings: []tgt.BindingMatcher{tgt.Match(keyB.Bind(6))}, + }.Run(t) +} + +// An operator which has a graph to create and one to delete is given one set of overrides. +func TestOverrider(t *testing.T) { + keyIn, keyA, keyB := tg.NewKey[int]("in"), tg.NewKey[int]("a"), tg.NewKey[int]("b") + keyD, keyUnused := tg.NewKey[int]("d"), tg.NewKey[int]("unused") + create := tgt.Must[tg.Graph](t)(tg.New("create", tg.WithTasks( + tg.SimpleTask1[int, int]( + "A", + keyA, + func(_ context.Context, in int) (int, error) { return in * 2, nil }, + keyIn, + ), + tg.SimpleTask1[int, int]( + "B", + keyB, + func(_ context.Context, a int) (int, error) { return a + 1, nil }, + keyA, + ), + ))) + del := tgt.Must[tg.Graph](t)(tg.New("delete", tg.WithTasks( + tg.SimpleTask1[int, int]( + "D", + keyD, + func(_ context.Context, in int) (int, error) { return in * 3, nil }, + keyIn, + ), + ))) + + overrider := tg.NewOverrider(keyA.Bind(10), keyD.Bind(20)) + if err := overrider.Check(create, del); err != nil { + t.Fatalf("Check(): %v", err) + } + + // Each graph takes the overrides which are for it, and ignores the others. + result, err := overrider.Run(context.Background(), create, keyIn.Bind(1)) + if err != nil { + t.Fatalf("running the graph to create: %v", err) + } + if got, err := keyB.Get(result); err != nil || got != 11 { + t.Errorf("b = %d, %v; want 11, from the override of a", got, err) + } + result, err = overrider.Run(context.Background(), del, keyIn.Bind(1)) + if err != nil { + t.Fatalf("running the graph to delete: %v", err) + } + if got, err := keyD.Get(result); err != nil || got != 20 { + t.Errorf("d = %d, %v; want 20, from the override", got, err) + } + + // An override for neither graph is found by Check, though each Run leaves it out. + stale := tg.NewOverrider(keyA.Bind(10), keyUnused.Bind(1)) + if err := stale.Check(create, del); !errors.Is(err, tg.ErrUnknownOverride) { + t.Errorf("Check() with a stale override: got %v; want ErrUnknownOverride", err) + } + if _, err := stale.Run(context.Background(), create, keyIn.Bind(1)); err != nil { + t.Errorf("Run() with an override for another graph: %v", err) + } +} + +// fakeGraph is a Graph which taskgraph.New didn't make. +type fakeGraph struct{ tg.Graph } + +func TestOverridesNeedAGraphMadeByTaskgraph(t *testing.T) { + if _, err := tg.RunWithOverrides(context.Background(), fakeGraph{}, nil, nil); err == nil { + t.Error( + "RunWithOverrides() on a Graph which taskgraph.New didn't make: got nil; want an error", + ) + } +} + +// A Test which has no overrides runs the Graph with Graph.Run, so it still works for a Graph which +// taskgraph.New didn't make. +func TestTestWithoutOverridesUsesGraphRun(t *testing.T) { + key := tg.NewKey[int]("a") + inner := tgt.Must[tg.Graph](t)(tg.New("inner", tg.WithTasks( + tg.SimpleTask("A", key, func(context.Context, tg.Binder) (int, error) { return 1, nil }), + ))) + + tgt.Test{ + Graph: fakeGraph{inner}, + WantBindings: []tgt.BindingMatcher{tgt.Match(key.Bind(1))}, + }.Run(t) +}