# S3

A collection of matchers that you can use to assert on S3 bucket objects.

Use the `s3Object()` helper function to specify which S3 object you are testing. It takes the following input parameters:

* `bucketName`: The bucket name where the object should be found.
* `key`: They key of the object you are looking for
* `retryPolicy`: An optional [node-retry](https://github.com/tim-kos/node-retry) options config. `sls-jest` will retry using the given retry policy until the test passes or all the retries are exhausted. This is useful in an asynchronous context.

### `toExist()`

Asserts whether an S3 object exists in the given bucket.

```typescript
await expect(
  s3Object({
    bucketName: 'my-bucket',
    key: 'path/to/file.txt',
  }),
).toExist();
```

### `toExistAndMatchObject<E>(expected: DeepPartial<E>)`

Asserts that an object exists in the given bucket, and matches a subset of the properties of a javascript object. It works similarly to jest's [toMatchObject](https://jestjs.io/docs/expect#tomatchobjectobject).

Note: This matcher can only be used with S3 objects that contain JSON-like data. If the content of the file cannot be parsed to a valid JSON, an error will be thrown.

```typescript
await expect(
  s3Object({
    bucketName: 'my-bucket',
    key: 'path/to/file.txt',
  }),
).toExistAndMatchObject<Message>({
  message: 'Hello world!',
});
```

### `toExistAndMatchSnapshot(propertiesOrHint?: string, hint?: string)`

Asserts that an item exists in the given bucket, and that it matches the most recent snapshot. It works similarly to jest's [toMatchSnapshot](https://jestjs.io/docs/expect#tomatchsnapshotpropertymatchers-hint).

```typescript
await expect(
  s3Object({
    bucketName: 'my-bucket',
    key: 'path/to/file.txt',
  }),
).toExistAndMatchSnapshot();
```

### `toExistAndMatchInlineSnapshot(propertiesOrHint?: string, hint?: string)`

Asserts that an object exists in the given bucket, and that it matches the most recent inline snapshot. It works similarly to jest's [toMatchInlineSnapshot](https://jestjs.io/docs/expect#tomatchinlinesnapshotpropertymatchers-inlinesnapshot).

```typescript
await expect(
  s3Object({
    bucketName: 'my-bucket',
    key: 'path/to/file.txt',
  }),
).toExistAndMatchInlineSnapshot(`
  Object {
    "message": 'Hello world!',
  }
`);
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://serverlessguru.gitbook.io/sls-jest/matchers/s3.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.