# Add/Edit Custom Test

This page will allow you to create a new custom test or edit an existing custom test.

## Test Guidance

{% hint style="danger" %}
Custom tests are read-only. You will not be able to write any information to tables or the client tenant.
{% endhint %}

Review the Test Guidance section for additional information on how to craft a custom test.

## Configuration Options

| Option                | Description                                                                                                                                                                                                                                                                          |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Script Name           | The display name for the test.                                                                                                                                                                                                                                                       |
| Category              | Existing Options: `License Management`, `Security`, `Compliance`, `User Management`, `Group Management`, `Device Management`, `Guest Management`, `General`. You are able to create custom categories by entering your desired category test and clicking "Add option: \<your text>" |
| Description           | Describes what the script checks or monitors.                                                                                                                                                                                                                                        |
| Risk Level            | Options: `Low`, `Medium`, `High`, `Critical`. Used for alert severity.                                                                                                                                                                                                               |
| Pillar                | Options: `Identity`, `Devices`, `Data`. Classifies which test category this belongs to.                                                                                                                                                                                              |
| User Impact           | Options: `Low`, `Medium`, `High`                                                                                                                                                                                                                                                     |
| Implementation Effort | Options: `Low`, `Medium`, `High`.                                                                                                                                                                                                                                                    |
| Result Display Type   | Options: `JSON` or `Markdown`. Controls how test failure output is rendered in CIPP test details.                                                                                                                                                                                    |
| Result Mode           | Options: `Auto`, `Always Pass`, `Always Info`, or `Always Investigate`. For `Auto` the script output determines pass/fail.                                                                                                                                                           |
| Enable Script         | Whether the test runs during scheduled test execution.                                                                                                                                                                                                                               |
| Notify on Alert       | Whether a notification fires when the test fails.                                                                                                                                                                                                                                    |

## Markdown/PowerShell

### Markdown Result Template

This is only displayed when the Result Display Type is set to Markdown. This allows you to define the Markdown that will be generated by the test result. See usage notes on the page for formatting, etc.

### PowerShell Script

This editor allows you to create the PowerShell script used in the test. See the usage notes on the page for how to construct the test script.

{% hint style="info" %}
Type % to insert replacement variables (e.g. %tenantid%, %defaultdomain%, or custom variables).
{% endhint %}

## Test Script Output

After saving the script, you are presented with the options below:

### Script Parameters (JSON)

Optional JSON object of parameters to pass to the script for the preview run. Multi-line text field. E.g. `{"DaysThreshold": 30}`.

### Run Test

This button will execute the test script against the currently selected tenant in [Tenant Select](/user-documentation/shared-features/menu-bar/tenant-select.md).

{% hint style="info" %}
Test runs on the page are preview only and are not written to the cache db.
{% endhint %}

***

## Feature Requests / Ideas

We value your feedback and ideas. Please raise any [feature requests](https://github.com/KelvinTegelaar/CIPP/issues/new?template=feature.yml) on GitHub.


---

# 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://docs.cipp.app/user-documentation/tools/custom-tests/add.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.