oliverdavies.uk/content/node.999e4bc2-3d7a-4d73-9f5e-62363accde44.yml

uuid:
  - value: 999e4bc2-3d7a-4d73-9f5e-62363accde44
langcode:
  - value: en
type:
  - target_id: daily_email
    target_type: node_type
    target_uuid: 8bde1f2f-eef9-4f2d-ae9c-96921f8193d7
revision_timestamp:
  - value: '2025-05-11T09:00:38+00:00'
revision_uid:
  - target_type: user
    target_uuid: b8966985-d4b2-42a7-a319-2e94ccfbb849
revision_log: {  }
status:
  - value: true
uid:
  - target_type: user
    target_uuid: b8966985-d4b2-42a7-a319-2e94ccfbb849
title:
  - value: |
      Why write custom assertions in your tests?
created:
  - value: '2023-07-03T00:00:00+00:00'
changed:
  - value: '2025-05-11T09:00:38+00:00'
promote:
  - value: false
sticky:
  - value: false
default_langcode:
  - value: true
revision_translation_affected:
  - value: true
path:
  - alias: /daily/2023/07/03/why-write-custom-assertions-in-your-tests
    langcode: en
body:
  - value: |
      <p>I'm refactoring some code on a client project - creating a Repository class to centralise some logic before implementing the next feature.</p>

      <p>The repository class is responsible for finding and returning any nodes with a specified field value and some base conditions (it must be the correct node type, published, etc.).</p>

      <h2 id="adding-a-custom-assertion">Adding a custom assertion</h2>

      <p>I'm using PHPUnit's native assertions to check it returns a Collection (I regularly include the <code>illuminate/collections</code> library from Laravel in other projects) and that each item is an instance of a <code>NodeInterface</code>, but there isn't an assertion to check each node is of the correct type.</p>

      <p>My initial implementation was to loop over each node and use <code>assertSame</code> on its bundle before refactoring to create an array of unique bundle names and comparing it to my expected names:</p>

      <pre><code class="language-php">self::assertSame(
        expected: [$nodeType],
        actual: $haystack
          -&gt;map(fn (NodeInterface $item): string =&gt; $item-&gt;bundle())
          -&gt;unique()
          -&gt;toArray(),
      );
      </code></pre>

      <h2 id="why-write-a-custom-assertion%3F">Why write a custom assertion?</h2>

      <p>Whilst this works, it likely won't be clear in the future what it's testing.</p>

      <p>My initial thought was to add a comment describing it, but then I decided to wrap it in a custom assertion - <code>assertContainsOnlyNodesOfType</code> - a private static function within my test class that wraps the native assertions.</p>

      <p>This approach makes the test more readable now and in the future and more domain-focused by giving it a descriptive name.</p>

      <p>It can be easily reused within the same test case or elsewhere.</p>

      <p>Although I only perform one assertion in this case, I can combine multiple assertions and perform any other required steps.</p>

      <p>Finally, I can contain any implementation details within the custom assertion. Here, I'm matching the result against an array of expected values, not just a single node type which is what I want. This detail can be contained within the assertion, making it easier to read and reuse in the future.</p>

              
    format: full_html
    processed: |
      <p>I'm refactoring some code on a client project - creating a Repository class to centralise some logic before implementing the next feature.</p>

      <p>The repository class is responsible for finding and returning any nodes with a specified field value and some base conditions (it must be the correct node type, published, etc.).</p>

      <h2 id="adding-a-custom-assertion">Adding a custom assertion</h2>

      <p>I'm using PHPUnit's native assertions to check it returns a Collection (I regularly include the <code>illuminate/collections</code> library from Laravel in other projects) and that each item is an instance of a <code>NodeInterface</code>, but there isn't an assertion to check each node is of the correct type.</p>

      <p>My initial implementation was to loop over each node and use <code>assertSame</code> on its bundle before refactoring to create an array of unique bundle names and comparing it to my expected names:</p>

      <pre><code class="language-php">self::assertSame(
        expected: [$nodeType],
        actual: $haystack
          -&gt;map(fn (NodeInterface $item): string =&gt; $item-&gt;bundle())
          -&gt;unique()
          -&gt;toArray(),
      );
      </code></pre>

      <h2 id="why-write-a-custom-assertion%3F">Why write a custom assertion?</h2>

      <p>Whilst this works, it likely won't be clear in the future what it's testing.</p>

      <p>My initial thought was to add a comment describing it, but then I decided to wrap it in a custom assertion - <code>assertContainsOnlyNodesOfType</code> - a private static function within my test class that wraps the native assertions.</p>

      <p>This approach makes the test more readable now and in the future and more domain-focused by giving it a descriptive name.</p>

      <p>It can be easily reused within the same test case or elsewhere.</p>

      <p>Although I only perform one assertion in this case, I can combine multiple assertions and perform any other required steps.</p>

      <p>Finally, I can contain any implementation details within the custom assertion. Here, I'm matching the result against an array of expected values, not just a single node type which is what I want. This detail can be contained within the assertion, making it easier to read and reuse in the future.</p>

              
    summary: null
field_daily_email_cta: {  }