feat(assertions): add stack tagging assertions

[jamestelfer]

Adds a Tag class to the assertions library that permits assertions against tags on synthesized CDK stacks.

Tags on AWS resources can be checked via assertions with the Template class, but since stack tags only appear on the cloud assembly manifest as a sibling of the template, a separate assertion mechanism is required.

API

class Tags {
  public static fromStack(stack: Stack) : Tags;
  public hasValues(props: any): void;
  public all(): { [key: string]: string };
}

Usage

This new class permits tests of the form:

import { App, Stack } from 'aws-cdk-lib';
import { Tags } from 'aws-cdk-lib/assertions';

const app = new App();
const stack = new Stack(app, 'MyStack', {
  tags: {
    'tag-name': 'tag-value'
  }
});

const tags = Tags.fromStack(stack);

// using a default 'objectLike' Matcher
tags.hasValues({
  'tag-name': 'tag-value'
});

// or another Matcher
tags.hasValues({
  'tag-name': Match.anyValue()
});

You can also get the set of tags to test them in other ways:

tags.all()

Issues

No tags case

One might expect that the case where no tags are present would match undefined or null, but since the Cloud Assembly API defaults tags to {} when none are present, this isn't possible. It's also not practical to directly test the artifact.manifest.properties.tags value directly, as there is a legacy case that the API handles. This means that the artifact.tags property is the best value to check against.

The tests for this PR show that matching with Match.absent() will fail when there are no tags, but testing against the empty object will succeed.

I think that this behaviour (defaulting to empty) will be OK, but potentially require a callout on the assertion method.

API method naming

The current suggested API went through some evolution, starting with:

class Tags {
  public static fromStack(stack: Stack) : Tags;
  public hasTags(props: any): void;
  public getTags():  { [key: string]: string };
}

But this stuttered, and getTags() wasn't compatible with Java.

I considered:

class Tags {
  public static fromStack(stack: Stack) : Tags;
  public hasValues(props: any): void;
  public values():  { [key: string]: string };
}

and

class Tags {
  public static fromStack(stack: Stack) : Tags;
  public has(props: any): void;
  public all():  { [key: string]: string };
}

... before settling on a mix of the two. I think the current iteration fits with the rest of the assertions API and makes sense by itself, but very open to changes.

Closes #27620.

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[aws-cdk-automation]

The pull request linter has failed. See the aws-cdk-automation comment below for failure reasons. If you believe this pull request should receive an exemption, please comment and provide a justification.

A comment requesting an exemption should contain the text Exemption Request. Additionally, if clarification is needed add Clarification Request to a comment.

[jamestelfer]

Exemption Request

As far as I can tell, the assertions library does not have integration tests, but I'm happy to be corrected.

[jamestelfer]

@SankyRed thanks for picking this up.

As far as I know there's nothing more I can do before review: tests pass and I don't think integration tests are required (see the exemption request).

Have I missed something that would allow a review?

[aws-cdk-automation]

This PR has been in the CHANGES REQUESTED state for 3 weeks, and looks abandoned. To keep this PR from being closed, please continue work on it. If not, it will automatically be closed in a week.

[jamestelfer]

@SankyRed / @pahud while the automation is pointing to this PR being stale, to the best of my knowlegde this PR is only awaiting (a) a response to the exemption request and (b) a code review.

Would it be possible for someone to indicate what further action I need to take?

[jamestelfer]

I've rebased this PR on the latest main.

[aws-cdk-automation]

AWS CodeBuild CI Report

• CodeBuild project: AutoBuildv2Project1C6BFA3F-wQm2hXv2jqQv
• Commit ID: 76744ae
• Result: SUCCEEDED
• Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

[aws-cdk-automation]

This PR has been deemed to be abandoned, and will be automatically closed. Please create a new PR for these changes if you think this decision has been made in error.

[aws-cdk-automation]

The pull request linter fails with the following errors:

❌ Features must contain a change to an integration test file and the resulting snapshot.

PRs must pass status checks before we can provide a meaningful review.

If you would like to request an exemption from the status checks or clarification on feedback, please leave a comment on this PR containing Exemption Request and/or Clarification Request.

[jamestelfer]

@SankyRed / @pahud I'm not sure why this was closed automatically: it was sitting awaiting review. As far as I knew, there was nothing more I could do, and I didn't want to ping constantly as that seemed rude.

What's the expected etiquette in this repo? Apologies, I'm new here!