diff --git a/Dummies.UnitTests/AmbientSeedScopeTests.cs b/Dummies.UnitTests/AmbientSeedScopeTests.cs index 2739fdfe..b14af111 100644 --- a/Dummies.UnitTests/AmbientSeedScopeTests.cs +++ b/Dummies.UnitTests/AmbientSeedScopeTests.cs @@ -11,7 +11,7 @@ namespace Dummies.UnitTests; /// /// The scope form of reproducibility: a handle a caller opens and disposes itself, for a test-framework adapter /// that observes a test through before/after hooks and therefore has no delegate to wrap (ADR-0035). The seed -/// behaviour must match Any.Reproducibly; what the scope adds is the replay instruction a +/// behaviour must match Any.Reproducibly; what the scope adds is the replay snippet a /// generation-failure diagnostic names, so a run pinned from outside the test body never advertises a call the /// test does not contain. /// @@ -123,7 +123,7 @@ public async Task TheScopeDoesNotLeakAcrossExecutionContexts() { Check.That(outside).IsNotEqualTo(inside); } - [Fact(DisplayName = "Without a replay instruction, a generation failure names Any.Reproducibly.")] + [Fact(DisplayName = "Without a replay snippet, a generation failure names Any.Reproducibly.")] public void WithoutAnInstructionTheFailureNamesTheDelegateRunner() { AnyGenerationException caught; @@ -137,7 +137,7 @@ public void WithoutAnInstructionTheFailureNamesTheDelegateRunner() { Check.That(caught.Message).Contains("Any.Reproducibly(1234, ...)"); } - [Fact(DisplayName = "With a replay instruction, a generation failure names it instead of Any.Reproducibly.")] + [Fact(DisplayName = "With a replay snippet, a generation failure names it instead of Any.Reproducibly.")] public void WithAnInstructionTheFailureNamesIt() { AnyGenerationException caught; @@ -152,7 +152,7 @@ public void WithAnInstructionTheFailureNamesIt() { Check.That(caught.Message).Not.Contains("Any.Reproducibly"); } - [Fact(DisplayName = "The replay instruction also reaches the partial-replay guidance.")] + [Fact(DisplayName = "The replay snippet also reaches the partial-replay guidance.")] public void TheInstructionReachesThePartialReplayGuidance() { AnyGenerationException caught; @@ -167,7 +167,7 @@ public void TheInstructionReachesThePartialReplayGuidance() { Check.That(caught.Message).Not.Contains("Any.Reproducibly"); } - [Fact(DisplayName = "The replay instruction is scoped: it does not outlive the scope that supplied it.")] + [Fact(DisplayName = "The replay snippet is scoped: it does not outlive the scope that supplied it.")] public void TheInstructionDoesNotOutliveItsScope() { using (Any.UseSeed(1, "[Reproducible(Seed = 1)]")) { } @@ -181,12 +181,12 @@ public void TheInstructionDoesNotOutliveItsScope() { Check.That(caught.Message).Not.Contains("[Reproducible"); } - [Fact(DisplayName = "UseSeed rejects a null replay instruction.")] + [Fact(DisplayName = "UseSeed rejects a null replay snippet.")] public void UseSeedRejectsANullInstruction() { Check.ThatCode(() => Any.UseSeed(1, null!)).Throws(); } - [Theory(DisplayName = "UseSeed rejects a blank replay instruction.")] + [Theory(DisplayName = "UseSeed rejects a blank replay snippet.")] [InlineData("")] [InlineData(" ")] public void UseSeedRejectsABlankInstruction(string instruction) { diff --git a/Dummies.Xunit.UnitTests/ReproducibleAttributeTests.cs b/Dummies.Xunit.UnitTests/ReproducibleAttributeTests.cs index 3f71c549..d210e4ad 100644 --- a/Dummies.Xunit.UnitTests/ReproducibleAttributeTests.cs +++ b/Dummies.Xunit.UnitTests/ReproducibleAttributeTests.cs @@ -100,7 +100,7 @@ public void AGenerationFailureNamesTheAttribute() { Check.That(caught.Seed).IsEqualTo(2026); Check.That(caught.Message).Contains("[Reproducible(Seed = 2026)]"); - // The whole point of the replay instruction: this test contains no Any.Reproducibly call, so naming + // The whole point of the replay snippet: this test contains no Any.Reproducibly call, so naming // one would send the reader to a call that is not there. Check.That(caught.Message).Not.Contains("Any.Reproducibly"); } diff --git a/Dummies.Xunit/README.nuget.md b/Dummies.Xunit/README.nuget.md index 6e92aa09..b3e31e69 100644 --- a/Dummies.Xunit/README.nuget.md +++ b/Dummies.Xunit/README.nuget.md @@ -41,7 +41,7 @@ Pin it to replay: [Fact, Reproducible(Seed = 1234)] public void Order_reference_is_accepted() { /* ... */ } -The same instruction is what a generation failure names, so a diagnostic never +The same snippet is what a generation failure names, so a diagnostic never points at a call the test does not contain. ## Where it applies diff --git a/Dummies.Xunit/ReproducibleAttribute.cs b/Dummies.Xunit/ReproducibleAttribute.cs index 56e00cbd..be0b3325 100644 --- a/Dummies.Xunit/ReproducibleAttribute.cs +++ b/Dummies.Xunit/ReproducibleAttribute.cs @@ -80,7 +80,7 @@ public int Seed { public override void Before(MethodInfo methodUnderTest, IXunitTest test) { int seed = _seed ?? NewSeed(); - Open.Value = new Scope(Any.UseSeed(seed, ReplayInstruction(seed)), seed, Open.Value); + Open.Value = new Scope(Any.UseSeed(seed, ReplaySnippet(seed)), seed, Open.Value); } /// @@ -104,7 +104,7 @@ public override void After(MethodInfo methodUnderTest, IXunitTest test) { /// What the reader must write to replay the run — the attribute with its seed, not the delegate runner the /// ambient source names by default, because a test carrying this attribute contains no such call. /// - private static string ReplayInstruction(int seed) { + private static string ReplaySnippet(int seed) { return $"[Reproducible(Seed = {seed})]"; } @@ -124,7 +124,7 @@ private static bool HasFailed() { /// internal static string? ReportFor(bool failed, int seed) { return failed - ? $"[Dummies] These arbitrary values were seeded with {seed}. Reproduce this run with {ReplayInstruction(seed)}." + ? $"[Dummies] These arbitrary values were seeded with {seed}. Reproduce this run with {ReplaySnippet(seed)}." : null; } diff --git a/Dummies/Any.cs b/Dummies/Any.cs index 8d08e318..c74d9657 100644 --- a/Dummies/Any.cs +++ b/Dummies/Any.cs @@ -428,34 +428,40 @@ public static IDisposable UseSeed(int seed) { } /// - /// Pins the ambient random context to and names, through - /// , what a reader must write to replay this run — the form a - /// test-framework adapter uses. A generation failure appends a reproduction guidance naming the mechanism that - /// actually replays the run; the default names Any.Reproducibly(seed, ...), which is the wrong - /// instruction for a run pinned from outside the test body, where replaying means changing what the adapter - /// reads instead. + /// Pins the ambient random context to and supplies the replay snippet — the + /// code a reader copies to replay this run — that generation-failure guidance will embed. This is the form a + /// test-framework adapter uses: the default snippet is Any.Reproducibly(seed, ...), which points at a + /// call a test pinned from outside its own body does not contain, where replaying means changing what the + /// adapter reads instead. /// /// /// - /// The instruction is quoted verbatim into the guidance, so pass what the reader must write — an attribute - /// with its seed argument, a runner setting — not a sentence about it. It is not validated beyond being - /// non-blank: a badly phrased instruction degrades the very diagnostic it is meant to improve. + /// A failure's guidance is one sentence embedding this snippet, so pass the code itself — an attribute with + /// its seed argument, a runner setting — not a sentence about it. It is quoted verbatim and validated only + /// for being non-blank: a badly phrased snippet degrades the very diagnostic it is meant to improve. /// + /// + /// + /// using (Any.UseSeed(1234, "[Reproducible(Seed = 1234)]")) { /* ... */ } + /// // A generation failure then reads: + /// // The arbitrary values were seeded with 1234; reproduce this run with [Reproducible(Seed = 1234)]. + /// + /// /// /// Everything else matches : the scope flows with the execution context, nests, /// and restores the previous ambient context when disposed. /// /// /// The seed pinning the ambient context's value sequence. - /// What a reader must write to replay this run, quoted verbatim into generation-failure guidance. + /// The code a reader copies to replay this run, quoted verbatim into generation-failure guidance. /// A handle that restores the previous ambient context when disposed. - /// Thrown when is null. - /// Thrown when is empty or white space. - public static IDisposable UseSeed(int seed, string replayInstruction) { - if (replayInstruction is null) { throw new ArgumentNullException(nameof(replayInstruction)); } - if (replayInstruction.Trim().Length == 0) { throw new ArgumentException("The replay instruction must name what a reader writes to replay the run; pass a non-blank instruction, or use the overload without one to name Any.Reproducibly(seed, ...).", nameof(replayInstruction)); } + /// Thrown when is null. + /// Thrown when is empty or white space. + public static IDisposable UseSeed(int seed, string replaySnippet) { + if (replaySnippet is null) { throw new ArgumentNullException(nameof(replaySnippet)); } + if (replaySnippet.Trim().Length == 0) { throw new ArgumentException("The replay snippet must be the code a reader copies to replay the run; pass a non-blank snippet, or use the overload without one to name Any.Reproducibly(seed, ...).", nameof(replaySnippet)); } - return AmbientRandomSource.UseSeed(seed, replayInstruction); + return AmbientRandomSource.UseSeed(seed, replaySnippet); } /// diff --git a/Dummies/AnyDerivation.cs b/Dummies/AnyDerivation.cs index 1c3978e8..31489e87 100644 --- a/Dummies/AnyDerivation.cs +++ b/Dummies/AnyDerivation.cs @@ -87,7 +87,7 @@ internal static T Invoke(Func invoke, RandomSource? source, bool reproduci int? seed = source?.Current.Seed; string message = $"Generation failed: {failure} ({exception.GetType().Name}: {exception.Message})."; if (source is not null) { - message += $" {(reproducible ? source.ReplayHint(seed!.Value) : source.PartialReplayHint(seed!.Value))}"; + message += $" {(reproducible ? source.ReplayGuidance(seed!.Value) : source.PartialReplayGuidance(seed!.Value))}"; } throw new AnyGenerationException(message, seed, exception); diff --git a/Dummies/CollectionState.cs b/Dummies/CollectionState.cs index 8db119dd..39dca861 100644 --- a/Dummies/CollectionState.cs +++ b/Dummies/CollectionState.cs @@ -251,8 +251,8 @@ private static AnyGenerationException Exhausted(RandomSource source, int reached // false) — even where it still carries a non-null source to name — so promising a full replay of its elements // would be false: qualify the hint instead. string replay = AnyDerivation.IsReproducible(culprit) - ? source.ReplayHint(seed) - : source.PartialReplayHint(seed); + ? source.ReplayGuidance(seed) + : source.PartialReplayGuidance(seed); string message = $"Could not generate a distinct collection of {Elements(target)}: {what} produced only {reached} distinct value(s) before the draw budget was exhausted. Loosen the count or widen the element generator's domain. {replay}"; return new AnyGenerationException(message, seed); diff --git a/Dummies/ContinuousIntervalSpec.cs b/Dummies/ContinuousIntervalSpec.cs index ec869793..370bb873 100644 --- a/Dummies/ContinuousIntervalSpec.cs +++ b/Dummies/ContinuousIntervalSpec.cs @@ -194,7 +194,7 @@ internal double Generate(RandomSource source) { double? free = NudgeToFree(candidate, ascending: true) ?? NudgeToFree(candidate, ascending: false); if (free is null) { throw new AnyGenerationException( - $"Generation failed: no {_typeName} value near the drawn candidate satisfies the exclusions. {source.ReplayHint(current.Seed)}", + $"Generation failed: no {_typeName} value near the drawn candidate satisfies the exclusions. {source.ReplayGuidance(current.Seed)}", current.Seed, new InvalidOperationException("No representable value in range remains after applying the exclusions.")); } diff --git a/Dummies/DecimalIntervalSpec.cs b/Dummies/DecimalIntervalSpec.cs index 4dbd26f7..fb04b7d8 100644 --- a/Dummies/DecimalIntervalSpec.cs +++ b/Dummies/DecimalIntervalSpec.cs @@ -228,7 +228,7 @@ internal decimal Generate(RandomSource source) { decimal? free = NudgeOnGrid(snapped, true) ?? NudgeOnGrid(snapped, false); if (free is null) { throw new AnyGenerationException( - $"Generation failed: no {_typeName} value near the drawn candidate satisfies the exclusions. {source.ReplayHint(current.Seed)}", + $"Generation failed: no {_typeName} value near the drawn candidate satisfies the exclusions. {source.ReplayGuidance(current.Seed)}", current.Seed, new InvalidOperationException("The grid nudge could not leave the excluded point within the allowed range.")); } @@ -244,7 +244,7 @@ internal decimal Generate(RandomSource source) { decimal next = Clamped(candidate + SmallestStep); if (next == candidate || budget-- == 0) { throw new AnyGenerationException( - $"Generation failed: no {_typeName} value near the drawn candidate satisfies the exclusions. {source.ReplayHint(current.Seed)}", + $"Generation failed: no {_typeName} value near the drawn candidate satisfies the exclusions. {source.ReplayGuidance(current.Seed)}", current.Seed, new InvalidOperationException("The exclusion nudge could not leave the excluded point within the allowed range.")); } diff --git a/Dummies/PublicAPI/net8.0/PublicAPI.Unshipped.txt b/Dummies/PublicAPI/net8.0/PublicAPI.Unshipped.txt index cd6cc5fe..e10931c3 100644 --- a/Dummies/PublicAPI/net8.0/PublicAPI.Unshipped.txt +++ b/Dummies/PublicAPI/net8.0/PublicAPI.Unshipped.txt @@ -492,7 +492,7 @@ static Dummies.Any.UInt32() -> Dummies.AnyUInt32! static Dummies.Any.UInt64() -> Dummies.AnyUInt64! static Dummies.Any.Uri() -> Dummies.AnyUri! static Dummies.Any.UseSeed(int seed) -> System.IDisposable! -static Dummies.Any.UseSeed(int seed, string! replayInstruction) -> System.IDisposable! +static Dummies.Any.UseSeed(int seed, string! replaySnippet) -> System.IDisposable! static Dummies.Any.WithSeed(int seed) -> Dummies.AnyContext! static Dummies.AnyExtensions.As(this Dummies.IAny! generator, System.Func! factory) -> Dummies.IAny! static Dummies.NullableExtensions.OrNull(this Dummies.IAny! generator) -> Dummies.IAny! diff --git a/Dummies/PublicAPI/netstandard2.0/PublicAPI.Unshipped.txt b/Dummies/PublicAPI/netstandard2.0/PublicAPI.Unshipped.txt index c6b1c1cd..e5a598cf 100644 --- a/Dummies/PublicAPI/netstandard2.0/PublicAPI.Unshipped.txt +++ b/Dummies/PublicAPI/netstandard2.0/PublicAPI.Unshipped.txt @@ -419,7 +419,7 @@ static Dummies.Any.UInt32() -> Dummies.AnyUInt32! static Dummies.Any.UInt64() -> Dummies.AnyUInt64! static Dummies.Any.Uri() -> Dummies.AnyUri! static Dummies.Any.UseSeed(int seed) -> System.IDisposable! -static Dummies.Any.UseSeed(int seed, string! replayInstruction) -> System.IDisposable! +static Dummies.Any.UseSeed(int seed, string! replaySnippet) -> System.IDisposable! static Dummies.Any.WithSeed(int seed) -> Dummies.AnyContext! static Dummies.AnyExtensions.As(this Dummies.IAny! generator, System.Func! factory) -> Dummies.IAny! static Dummies.NullableExtensions.OrNull(this Dummies.IAny! generator) -> Dummies.IAny! diff --git a/Dummies/RandomSource.cs b/Dummies/RandomSource.cs index e3bcac67..2b17a5dc 100644 --- a/Dummies/RandomSource.cs +++ b/Dummies/RandomSource.cs @@ -13,24 +13,31 @@ internal abstract class RandomSource { internal abstract SeededRandom Current { get; } /// - /// The reproduction guidance to append to a generation-failure message, phrased for this kind of source. The - /// ambient source points at Any.Reproducibly(seed, ...) — or at whatever instruction the opener of the - /// current scope supplied, since a run pinned by a test-framework - /// adapter is replayed by changing what the adapter reads, not by adding a call the test never had; a fixed - /// Any.WithSeed(...) context replays deterministically on its own, so pinning the ambient source would - /// not apply — naming the wrong instruction is exactly the misleading diagnostic this method exists to avoid. + /// The reproduction guidance to append to a generation-failure message, phrased for this kind of source: one + /// sentence, which embeds a replay snippet — the code the reader copies. The two words are + /// a whole and its part, and they are never interchangeable: guidance is the sentence, a snippet is the + /// fragment it names. /// - internal abstract string ReplayHint(int seed); + /// + /// Which snippet the sentence names depends on how the run was pinned, and getting that wrong is the whole + /// point of this method existing. The ambient source names Any.Reproducibly(seed, ...) — or whatever + /// snippet the opener of the current scope supplied, since a run pinned + /// by a test-framework adapter is replayed by changing what the adapter reads, not by adding a call the test + /// never had. A fixed Any.WithSeed(...) context replays deterministically on its own, so pinning the + /// ambient source would not apply. Naming a snippet the reader's code does not contain is exactly the + /// misleading diagnostic this method exists to avoid. + /// + internal abstract string ReplayGuidance(int seed); /// /// The reproduction guidance for a failure whose seeded draws this source drove but whose result also depends on /// a generator that does not draw from this source — a foreign , or a derivation built over /// one (including a Combine that mixes a foreign operand with a sourced one). It names the same replay - /// mechanism as for the seeded part, but scopes the promise to it: the foreign values + /// mechanism as for the seeded part, but scopes the promise to it: the foreign values /// are not reproducible from this seed alone, so claiming a full replay would be the misleading diagnostic the /// seed reporting exists to avoid. /// - internal abstract string PartialReplayHint(int seed); + internal abstract string PartialReplayGuidance(int seed); } @@ -71,9 +78,9 @@ internal static IDisposable UseSeed(int seed) { return UseSeed(seed, null); } - internal static IDisposable UseSeed(int seed, string? replayInstruction) { + internal static IDisposable UseSeed(int seed, string? replaySnippet) { AmbientState? previous = State.Value; - State.Value = new AmbientState(new SeededRandom(seed), replayInstruction); + State.Value = new AmbientState(new SeededRandom(seed), replaySnippet); return new SeedScope(previous); } @@ -94,21 +101,22 @@ internal override SeededRandom Current { } } - internal override string ReplayHint(int seed) { - return $"The arbitrary values were seeded with {seed}; reproduce this run with {ReplayInstruction(seed)}."; + internal override string ReplayGuidance(int seed) { + return $"The arbitrary values were seeded with {seed}; reproduce this run with {ReplaySnippet(seed)}."; } - internal override string PartialReplayHint(int seed) { - return $"The seeded draws were made with {seed} ({ReplayInstruction(seed)}), but some values come from a generator that does not draw from this source, so they are not reproducible from this seed alone."; + internal override string PartialReplayGuidance(int seed) { + return $"The seeded draws were made with {seed} ({ReplaySnippet(seed)}), but some values come from a generator that does not draw from this source, so they are not reproducible from this seed alone."; } /// - /// What the reader must write to replay the current run: the instruction the opener of the scope supplied, or - /// the delegate runner when nothing was supplied. Read from the scope rather than fixed on the source, because - /// the ambient source is pinned by several mechanisms and each is replayed differently. + /// The code the reader copies to replay the current run — the fragment the guidance sentence embeds, never the + /// sentence itself: the snippet the opener of the scope supplied, or the delegate runner when none was. Read + /// from the scope rather than fixed on the source, because the ambient source is pinned by several mechanisms + /// and each is replayed differently. /// - private static string ReplayInstruction(int seed) { - return State.Value?.ReplayInstruction ?? $"Any.Reproducibly({seed}, ...)"; + private static string ReplaySnippet(int seed) { + return State.Value?.ReplaySnippet ?? $"Any.Reproducibly({seed}, ...)"; } #region Nested types @@ -116,13 +124,13 @@ private static string ReplayInstruction(int seed) { /// The ambient state a seed scope installs: the seeded generator, and how to replay the run that uses it. private sealed class AmbientState { - internal AmbientState(SeededRandom random, string? replayInstruction) { - Random = random; - ReplayInstruction = replayInstruction; + internal AmbientState(SeededRandom random, string? replaySnippet) { + Random = random; + ReplaySnippet = replaySnippet; } - internal SeededRandom Random { get; } - internal string? ReplayInstruction { get; } + internal SeededRandom Random { get; } + internal string? ReplaySnippet { get; } } @@ -163,11 +171,11 @@ internal FixedRandomSource(int seed) { internal override SeededRandom Current => _random; - internal override string ReplayHint(int seed) { + internal override string ReplayGuidance(int seed) { return $"The arbitrary values were drawn from Any.WithSeed({seed}), which already replays deterministically."; } - internal override string PartialReplayHint(int seed) { + internal override string PartialReplayGuidance(int seed) { return $"The seeded draws were made from Any.WithSeed({seed}), but some values come from a generator that does not draw from it, so they are not reproducible from this seed alone."; } diff --git a/Dummies/StringSpec.cs b/Dummies/StringSpec.cs index fcdae4c6..77b1bc3c 100644 --- a/Dummies/StringSpec.cs +++ b/Dummies/StringSpec.cs @@ -276,7 +276,7 @@ private string BuildCandidate(Random random) { private AnyGenerationException Exhausted(RandomSource source) { int seed = source.Current.Seed; // A string generator draws only from its own source, so the seed replays the run fully — never the partial hint. - string replay = source.ReplayHint(seed); + string replay = source.ReplayGuidance(seed); string message = $"Could not generate a string that satisfies the declared shape while excluding {DescribeExcluded()}: " + $"no candidate survived {V(ExclusionRedrawBudget)} draws, so the exclusions leave the shape unsatisfiable " + diff --git a/Dummies/UriSpec.cs b/Dummies/UriSpec.cs index 641fbf2d..5a6002c2 100644 --- a/Dummies/UriSpec.cs +++ b/Dummies/UriSpec.cs @@ -228,7 +228,7 @@ private string BuildRelative(RandomSource source) { if (_pathMode == UriPathMode.Exact) { int seed = source.Current.Seed; throw new AnyGenerationException( - "A relative URI with exactly 0 path segments and no query, fragment or root is empty, which is not a valid URI reference. Add a query, a fragment, Rooted(), or a positive segment count. " + source.ReplayHint(seed), + "A relative URI with exactly 0 path segments and no query, fragment or root is empty, which is not a valid URI reference. Add a query, a fragment, Rooted(), or a positive segment count. " + source.ReplayGuidance(seed), seed); } diff --git a/doc/handwritten/for-maintainers/adr/0038-open-the-ambient-seed-scope-to-adapters.fr.md b/doc/handwritten/for-maintainers/adr/0038-open-the-ambient-seed-scope-to-adapters.fr.md index f0856c40..a0f4b6a4 100644 --- a/doc/handwritten/for-maintainers/adr/0038-open-the-ambient-seed-scope-to-adapters.fr.md +++ b/doc/handwritten/for-maintainers/adr/0038-open-the-ambient-seed-scope-to-adapters.fr.md @@ -33,13 +33,13 @@ l'autre, ce qu'aucun chemin public ne permet. Deux faits supplémentaires pèsent sur la forme de cette ouverture. -* **Les échecs de génération portent une instruction de rejeu.** Lorsqu'un +* **Les échecs de génération portent un extrait de rejeu.** Lorsqu'un générateur échoue — typiquement une fabrique rejetant une valeur tirée — le message d'exception ajoute une indication nommant le mécanisme qui rejoue réellement l'exécution. Cette indication est choisie par type de source : la source ambiante nomme l'exécuteur à délégué, un contexte isolé se nomme - lui-même, parce que les deux se rejouent différemment. Nommer une instruction - que le code de l'appelant n'utilise pas est un diagnostic trompeur, et l'éviter + lui-même, parce que les deux se rejouent différemment. Nommer un extrait + que le code de l'appelant ne contient pas est un diagnostic trompeur, et l'éviter est la raison même pour laquelle l'indication varie. * **Aucune des formulations existantes ne convient à une exécution fixée par un adaptateur.** Un test dont la graine a été fixée par un adaptateur ne contient @@ -65,7 +65,7 @@ aucune autorisation de ce type aujourd'hui. ## Décision `Dummies` expose la portée de graine ambiante sous forme de poignée publique et -disposable, dont l'ouvreur peut fournir l'instruction de rejeu que les +disposable, dont l'ouvreur peut fournir l'extrait de rejeu que les diagnostics d'échec de génération nommeront. ## Justification @@ -84,14 +84,14 @@ diagnostics d'échec de génération nommeront. autre framework plus tard » une décision additive ne touchant rien ici — ce qui est précisément la propriété qui permet de prendre la décision xUnit de façon étroite, sans trancher le reste. -* **Porter l'instruction de rejeu préserve un invariant que la bibliothèque +* **Porter l'extrait de rejeu préserve un invariant que la bibliothèque applique déjà.** Le diagnostic nomme le mécanisme qui s'applique ; c'est d'ailleurs pourquoi l'indication varie selon la source. Un adaptateur introduit une troisième manière de fixer la source ambiante, et sans moyen de le dire il hériterait de la formulation de l'exécuteur à délégué — annonçant, à un développeur dont le test ne contient aucun appel de ce genre, exactement - l'instruction trompeuse que le mécanisme existe pour empêcher. Laisser - l'ouvreur nommer l'instruction prolonge ce design au lieu de le contourner. + l'extrait trompeur que le mécanisme existe pour empêcher. Laisser + l'ouvreur nommer l'extrait prolonge ce design au lieu de le contourner. * **La forme « portée disposable » est déjà l'idiome maison.** L'ADR-0006 l'a établie pour les surcharges d'horloge et d'identifiants d'instance, si bien que l'ajout se reconnaît comme la même chose plutôt que comme un second mécanisme @@ -111,7 +111,7 @@ besoin de sa propre autorisation et donc de sa propre modification de `Dummies` et parce qu'elle couple les identités d'assembly des deux packages pour une capacité qui n'est pas, en elle-même, privée. -### Exposer la portée sans instruction de rejeu +### Exposer la portée sans extrait de rejeu Considérée comme le plus petit ajout possible, reportant la question du diagnostic jusqu'à l'existence d'un adaptateur. Rejetée parce qu'elle livre le @@ -125,7 +125,7 @@ perturbateur. Considérée parce qu'une indication ne nommant aucun mécanisme ne peut pas nommer le mauvais. Rejetée parce qu'elle fait payer le cas rare par le cas dominant : -les utilisateurs de l'exécuteur à délégué perdraient une instruction actionnable +les utilisateurs de l'exécuteur à délégué perdraient un extrait actionnable — l'appel exact à écrire — pour accommoder un appelant qui peut simplement énoncer la sienne. @@ -142,7 +142,7 @@ passer : il observe le test, il ne l'invoque pas. * Tout framework de test peut être adapté sans accès privilégié à `Dummies` et sans modification supplémentaire de celui-ci, si bien que chaque adaptateur supplémentaire est une décision indépendante et additive. -* Une exécution dont un adaptateur a fixé la graine rapporte une instruction de +* Une exécution dont un adaptateur a fixé la graine rapporte un extrait de rejeu correspondant au code de l'appelant, ce qui préserve la garantie qu'un diagnostic ne nomme jamais un mécanisme que le lecteur n'utilise pas. * L'ajout réutilise l'idiome établi de portée disposable au lieu d'introduire une @@ -153,7 +153,7 @@ passer : il observe le test, il ne l'invoque pas. * Une troisième manière publique de contrôler la graine, aux côtés de l'exécuteur à délégué et du contexte isolé. La documentation doit garder les trois distinctes et dire laquelle le lecteur cherche. -* L'instruction de rejeu est fournie par l'appelant et ne peut pas être validée +* L'extrait de rejeu est fourni par l'appelant et ne peut pas être validé par `Dummies` ; une formulation maladroite dégrade donc le diagnostic qu'elle devait améliorer. @@ -174,7 +174,7 @@ passer : il observe le test, il ne l'invoque pas. * Documenter l'ajout dans le guide utilisateur, en anglais et en français de concert, en distinguant les trois manières de contrôler la graine et en désignant le cas de l'adaptateur comme celui pour lequel cette poignée existe. -* Réexaminer la forme portant l'instruction si un second adaptateur montre +* Réexaminer la forme portant l'extrait si un second adaptateur montre qu'elle reste habituellement inutilisée. ## Références diff --git a/doc/handwritten/for-maintainers/adr/0038-open-the-ambient-seed-scope-to-adapters.md b/doc/handwritten/for-maintainers/adr/0038-open-the-ambient-seed-scope-to-adapters.md index 6b357dde..d17bb191 100644 --- a/doc/handwritten/for-maintainers/adr/0038-open-the-ambient-seed-scope-to-adapters.md +++ b/doc/handwritten/for-maintainers/adr/0038-open-the-ambient-seed-scope-to-adapters.md @@ -29,13 +29,13 @@ hook and close it in the other, which no public path allows. Two further facts bear on the shape of that opening. -* **Generation failures carry a replay instruction.** When a generator fails — +* **Generation failures carry a replay snippet.** When a generator fails — typically a factory rejecting a drawn value — the exception message appends a - hint naming the mechanism that actually replays the run. That hint is chosen + guidance naming the mechanism that actually replays the run. That guidance is chosen per kind of source: the ambient source names the delegate runner, an isolated context names itself, because the two are replayed differently. Naming an - instruction the caller's code does not use is a misleading diagnostic, and - avoiding it is the reason the hint varies at all. + snippet the caller's code does not contain is a misleading diagnostic, and + avoiding it is the reason the guidance varies at all. * **Neither existing phrasing fits an adapter-pinned run.** A test whose seed was pinned by an adapter contains no call to the delegate runner, and replaying it means changing whatever the adapter reads — an attribute argument, a runner @@ -57,7 +57,7 @@ The alternative access path — granting a named companion package access to ## Decision `Dummies` exposes the ambient seed scope as a public, disposable handle whose -opener may supply the replay instruction that generation-failure diagnostics will +opener may supply the replay snippet that generation-failure diagnostics will name. ## Rationale @@ -74,13 +74,13 @@ name. handle makes "adapt another framework later" an additive decision that touches nothing here — which is precisely the property that lets the xUnit decision be taken narrowly, without deciding the rest. -* **Carrying the replay instruction preserves an invariant the library already +* **Carrying the replay snippet preserves an invariant the library already enforces.** The diagnostic names the mechanism that applies; that is why the - hint varies by source in the first place. An adapter introduces a third way of + guidance varies by source in the first place. An adapter introduces a third way of pinning the ambient source, and without a way to say so it would inherit the delegate runner's phrasing — advertising, to a developer whose test contains no - such call, exactly the misleading instruction the mechanism exists to prevent. - Letting the opener name the instruction extends that design rather than + such call, exactly the misleading snippet the mechanism exists to prevent. + Letting the opener name the snippet extends that design rather than working around it. * **The disposable-scope shape is already the house idiom.** ADR-0006 established it for the clock and instance-id overrides, so the addition is recognizable as @@ -99,19 +99,19 @@ companion — every other adapter, first-party or third-party, would need its ow grant and therefore its own change to `Dummies` — and because it couples the two packages' assembly identities for a capability that is not, in itself, private. -### Expose the scope without a replay instruction +### Expose the scope without a replay snippet Considered as the smallest possible addition, deferring the diagnostic question until an adapter exists. Rejected because it ships the misleading diagnostic the -hint mechanism exists to prevent: every adapter-pinned run whose generation fails +guidance mechanism exists to prevent: every adapter-pinned run whose generation fails would tell the developer to use a call their test does not contain. It also defers a parameter onto a published member, which is the more disruptive order. -### Phrase the ambient hint neutrally, so it is never wrong +### Phrase the ambient guidance neutrally, so it is never wrong -Considered because a hint that names no mechanism cannot name the wrong one. +Considered because guidance that names no mechanism cannot name the wrong one. Rejected because it pays for the rarer case with the dominant one: the delegate -runner's users would lose an actionable instruction — the exact call to write — +runner's users would lose an actionable snippet — the exact call to write — to accommodate a caller that can simply state its own. ### Let adapters reuse the delegate runner @@ -127,7 +127,7 @@ does not invoke it. * Any test framework can be adapted without privileged access to `Dummies` and without a further change to it, so each additional adapter is an independent, additive decision. -* A run whose seed an adapter pinned reports a replay instruction that matches +* A run whose seed an adapter pinned reports a replay snippet that matches the caller's own code, keeping the guarantee that a diagnostic never names a mechanism the reader does not use. * The addition reuses the established disposable-scope idiom instead of @@ -138,7 +138,7 @@ does not invoke it. * A third public way to control seeding, alongside the delegate runner and the isolated context. The documentation must keep the three distinct and say which one a reader wants. -* The replay instruction is supplied by the caller and cannot be validated by +* The replay snippet is supplied by the caller and cannot be validated by `Dummies`, so a badly phrased one degrades the diagnostic it was meant to improve. @@ -157,7 +157,7 @@ does not invoke it. * Document the addition in the user guide, in English and French in lockstep, distinguishing the three ways to control seeding and naming the adapter case as the one this handle exists for. -* Revisit the instruction-carrying form if a second adapter shows it is +* Revisit the snippet-carrying form if a second adapter shows it is habitually left unused. ## References diff --git a/doc/handwritten/for-users/ArbitraryTestValues.en.md b/doc/handwritten/for-users/ArbitraryTestValues.en.md index 8a34e527..1192a3de 100644 --- a/doc/handwritten/for-users/ArbitraryTestValues.en.md +++ b/doc/handwritten/for-users/ArbitraryTestValues.en.md @@ -99,7 +99,7 @@ scope.Dispose(); The scope flows with the execution context and nests exactly like `Reproducibly`, and disposing restores whatever was pinned before. What it does **not** do is report the seed when the test fails: whoever opens the scope owns telling the reader which seed to replay. -That ownership extends to the replay instruction. When a generator itself fails, the `AnyGenerationException` message names how to replay the run — by default `Any.Reproducibly(1234, ...)`, which is the wrong instruction for a test that contains no such call. A caller that pins the seed from outside says so, and its instruction is quoted verbatim instead: +That ownership extends to the replay snippet. When a generator itself fails, the `AnyGenerationException` message names how to replay the run — by default `Any.Reproducibly(1234, ...)`, which is the wrong instruction for a test that contains no such call. A caller that pins the seed from outside says so, and its instruction is quoted verbatim instead: ```csharp Dummies.Any.UseSeed(1234, "[Reproducible(Seed = 1234)]"); diff --git a/doc/handwritten/for-users/ArbitraryTestValues.fr.md b/doc/handwritten/for-users/ArbitraryTestValues.fr.md index e5e54e68..1ea06da9 100644 --- a/doc/handwritten/for-users/ArbitraryTestValues.fr.md +++ b/doc/handwritten/for-users/ArbitraryTestValues.fr.md @@ -99,7 +99,7 @@ scope.Dispose(); La portée suit le contexte d’exécution et s’imbrique exactement comme `Reproducibly`, et la disposer restaure ce qui était fixé auparavant. Ce qu’elle ne fait **pas**, c’est rapporter la graine quand le test échoue : c’est à celui qui ouvre la portée de dire au lecteur quelle graine rejouer. -Cette responsabilité s’étend à l’instruction de rejeu. Lorsqu’un générateur échoue lui-même, le message de l’`AnyGenerationException` nomme la façon de rejouer l’exécution — par défaut `Any.Reproducibly(1234, ...)`, ce qui est la mauvaise instruction pour un test ne contenant aucun appel de ce genre. Un appelant qui fixe la graine depuis l’extérieur l’énonce, et son instruction est citée telle quelle à la place : +Cette responsabilité s’étend à l’extrait de rejeu. Lorsqu’un générateur échoue lui-même, le message de l’`AnyGenerationException` nomme la façon de rejouer l’exécution — par défaut `Any.Reproducibly(1234, ...)`, ce qui est la mauvaise instruction pour un test ne contenant aucun appel de ce genre. Un appelant qui fixe la graine depuis l’extérieur l’énonce, et son instruction est citée telle quelle à la place : ```csharp Dummies.Any.UseSeed(1234, "[Reproducible(Seed = 1234)]");