Clear Tests for Jira

Create and edit a test

Select New test. Fields:

• Title, Objective, Preconditions
• Type: Manual, Gherkin or Automated
• Status: Draft, Ready or Deprecated
• Priority: Low, Medium, High or Critical
• Labels (separated by commas), Estimated minutes, Automation key, Folder
• Steps: for each step an Action, Test data and Expected result. Use Up, Down and Remove to arrange steps and Add step to add one.
• Gherkin: for a Gherkin test, write the scenario here.
• Parameters: a table of values. Use Add column, Add row, Remove row and Remove column. Each row runs the test once with those values. A table can have up to 20 columns and 100 rows with unique column names.

When you open an existing test, a Hints list appears under the steps if there is something to point out. It helps you write better tests: a step without an expected result, a vague step, another test in the folder with the same title, no work item linked, or a linked work item that changed.

Try it:

1. Select New test and type a title.
2. Add two steps and give each an Expected result.
3. Select Save. The window closes and the new test shows in the list. When you save an existing test, the text "Saved." appears at the top of the window.

If someone else saved the test while you were editing it, Clear Tests asks you to reload so nobody overwrites the other's work.

Version history

Every save creates a new version. Open Version history in the editor to see earlier versions, each with its save time. Select Compare to see what differs from the current test: the changed fields (title, objective, preconditions, type, status, priority, labels, Gherkin text, estimated minutes, automation key and parameters) and the steps that come back, are removed or change, with the text of the version and of the current test side by side. Select Restore to bring one back; you are asked to confirm first. The restored text becomes the newest version, and older versions stay in the history. A cycle item remembers the version of the test it was added with, so a result always shows the steps that were run.

Try it: edit and save a test twice, open Version history, select Compare on the first version and then Restore.

Folders

The Folders panel organizes tests in several levels. Select New folder, type a Folder name and select Create. Use Rename, Move to... and Delete on a folder. Only an empty folder can be deleted. A folder cannot be moved into itself or one of its subfolders. All tests shows everything and No folder shows tests outside any folder.

Search, filters and bulk actions

Search by Search title or objective. Filter by Status, Type, Priority, Label, AI drafts and Needs review. Select Clear filters to reset. The list shows 50 tests per page; use Next and Previous.

Select tests with the checkboxes (or Select all on this page) to use the bulk actions: Move to..., Set status, Add label, Add to cycle and Delete.

Trash

Delete moves tests to the trash. Open the Trash filter to see them and select Restore. Tests in the trash are deleted for good after 30 days.

Test coverage panel on a work item

Open any work item and expand the Tests section in the right-hand column (it starts collapsed). Under Test coverage it shows the number of tests, the counts of passed, failed and not run tests, and the Latest result of each test.

• Create test: writes a new test for this work item and links it.
• Link test: find an existing test by title or objective, select it and choose Link selected.
• Unlink: removes the link. The test itself is kept.
• If some linked tests are in projects you cannot view, the panel shows only a count ("N tests in projects you can't view").

If the work item's summary or description changes, its linked tests are marked Needs review.

Try it: open a requirement, select Create test, type a title and confirm. The panel now shows 1 test.

Search with JQL

Clear Tests writes a small property on each linked work item, so JQL works anywhere in Jira:

Write the no-tests searches exactly as shown. A work item that never had a test has no cleartests property, so testCount = 0 or testStatus = none alone does not find it; is EMPTY does.

testStatus is one of none, not-run, failed, partial or passed. A work item is failed if any linked test has a latest result of Failed or Blocked, passed if all passed, not-run if none has run, and partial otherwise.

Create, edit, clone, close, delete

• New cycle opens the form: Name, Description, Fix version, Sprint, Environment, Start date, End date. A new cycle is Planned; it becomes Active when you save the first result, and Done when you close it.
• Edit changes the cycle.
• Clone copies the cycle with its tests but without results, for example for a regression round.
• Close cycle locks the results. You cannot record results or add tests to a closed cycle, but you can still link bugs.
• Delete removes the cycle and all its results for good, after a confirmation.

Add tests

Select Add tests, then Add from:

• Folder – all tests in a folder
• Label – tests with a label
• Search – by title or objective; select tests and choose Add selected
• Work items in a version – finds the requirement work items in the version and adds the tests that cover them

Only the first 50 tests are shown in a search; narrow the search to see the rest.

Assign

Select items in the table, choose a person under Assign to and select Assign selected. Clear assignee removes it. Filter the table by Assignee (Me, Anyone or Unassigned).

Run a test

Select Run on an item (or Run first test). On a work item, the Test coverage panel also has Run next to each test: it opens the project page at the test's latest active cycle. If the test is in no active cycle, the panel shows Not in an active cycle. The runner shows one test at a time with its Preconditions, Objective and each step with Action, Test data and Expected result.

• Choose Pass, Fail, Block or Skip for each step. The result of the test is calculated from the steps.
• Pass all marks all steps as passed.
• Type an Actual result and a Comment.
• Use Start timer, Stop timer and Reset to record Time.
• If the test has a parameter table, each row is an iteration ("Row 1 of 3: user = admin"). Each iteration has its own result.
• Save result stores the result. Next test and Previous test save first, so you do not lose results. If you close with unsaved changes, you can choose Save and close or Discard.

The statuses are fixed: Not run, In progress, Passed, Failed, Blocked and Skipped.

Try it:

1. Open a cycle with two tests and select Run first test.
2. Select Pass on step 1 and Fail on step 2.
3. Select Save result, then Next test.

Bugs

On a CI cycle with failures, select Create bugs for N new failures to create one bug for each failed test that has no open bug yet. Each bug is created as you and links to the work items the test covers. One run creates up to 50 bugs. The bugs are created in steps while you keep the page open, and a line shows how many are done. If there are more than 50 new failures, the message says how many are left and you run it again. Running it twice never creates a second bug for the same failure.

For a single result, on a failed step or a failed test, select Create bug. If the test has steps, the dialog lets you choose the Failed step (a step, or The whole test). The dialog shows the Summary, Steps to reproduce, Expected and Actual that the bug will get; you can add your own text in Notes. The new work item is created as you, with the headings Preconditions, Steps to reproduce, Expected, Actual, Environment and Test cycle, and a link to the cycle. It is linked to the requirement with a "relates to" link.

• Link existing bug: type the work item key and select Link.
• Bugs in this cycle lists every bug that is linked to the cycle.
• The work item type for bugs is set in Settings (default: Bug, or the first type that is not a sub-task).

CI setup

Send JUnit XML or Cucumber JSON reports from your build with one curl line. Each project has its own tokens; a token works only for its project. Only project admins see the CI address and tokens.

1. Open Import & CI and CI, then select Create token.
2. Type a Token name (for example the name of the pipeline) and create it.
3. Copy the token now. It is shown only once and cannot be read again. Store it in your CI system as a secret named CLEARTESTS_TOKEN.
4. Copy the CI address (shown on the page), choose your CI system under Pipeline examples and paste the snippet in your pipeline. Change report.xml to the path of your report. For Cucumber JSON send the .json file in the same way.

The address accepts these optional parameters: cycle (cycle name, default "CI" or "CI – branch name"), build, branch, commit, version and environment.

environment and version are shown on the cycle. build, branch and commit are stored with each run but are not shown on screen. A cycle that a build creates appears in the Cycles list and in Reports after you reload the page. A test created from a CI report is saved with the status Ready.

Results are matched to tests by the automation key (class.name). A test that does not exist is created as an Automated test in the folder Automated/<suite>. You can turn that off in Settings. CI never creates Jira work items. Reports are limited to 5 MB and 20,000 results per call, and one token can send 60 calls a minute. If the cycle is closed you get an error and must choose another cycle name. A report with more than 20,000 results is refused at once. The Atlassian platform limits how many uploads run at the same time, so a pipeline with many parallel jobs should upload one report at a time or retry when a call fails. A project can store about 100 MB of CI results per day (UTC); beyond that the upload answers 429 with a daily-limit message, and the pipeline should retry the next day. When the site's app storage is 90 % full, uploads and file imports stop (507) until space is freed by shortening the CI retention or deleting cycles.

The five snippets, as shown in the app (replace the address with yours):

GitHub Actions:

- name: Send test report to Clear Tests
  if: always()
  env:
    CLEARTESTS_URL: <your CI address>
    CLEARTESTS_TOKEN: ${{ secrets.CLEARTESTS_TOKEN }}
  run: |
    curl -X POST "$CLEARTESTS_URL?cycle=CI&build=${{ github.run_number }}&branch=${{ github.ref_name }}&commit=${{ github.sha }}" \
      -H "Authorization: Bearer $CLEARTESTS_TOKEN" --data-binary @report.xml

GitLab CI:

send-report:
  stage: .post
  when: always
  variables:
    CLEARTESTS_URL: <your CI address>
  script:
    - 'curl -X POST "$CLEARTESTS_URL?cycle=CI&build=$CI_PIPELINE_IID&branch=$CI_COMMIT_REF_NAME&commit=$CI_COMMIT_SHA" -H "Authorization: Bearer $CLEARTESTS_TOKEN" --data-binary @report.xml'

Bitbucket Pipelines:

- step:
    name: Send test report to Clear Tests
    script:
      - export CLEARTESTS_URL="<your CI address>"
      - 'curl -X POST "$CLEARTESTS_URL?cycle=CI&build=$BITBUCKET_BUILD_NUMBER&branch=$BITBUCKET_BRANCH&commit=$BITBUCKET_COMMIT" -H "Authorization: Bearer $CLEARTESTS_TOKEN" --data-binary @report.xml'

Jenkins:

post {
  always {
    withCredentials([string(credentialsId: 'cleartests-token', variable: 'CLEARTESTS_TOKEN')]) {
      sh '''curl -X POST "<your CI address>?cycle=CI&build=$BUILD_NUMBER&branch=$BRANCH_NAME&commit=$GIT_COMMIT" \
        -H "Authorization: Bearer $CLEARTESTS_TOKEN" --data-binary @report.xml'''
    }
  }
}

Azure DevOps:

- script: |
    curl -X POST "$CLEARTESTS_URL?cycle=CI&build=$(Build.BuildNumber)&branch=$(Build.SourceBranchName)&commit=$(Build.SourceVersion)" \
      -H "Authorization: Bearer $CLEARTESTS_TOKEN" --data-binary @report.xml
  displayName: Send test report to Clear Tests
  condition: always()
  env:
    CLEARTESTS_URL: <your CI address>
    CLEARTESTS_TOKEN: $(CLEARTESTS_TOKEN)

To stop a pipeline, select Revoke on its token. Pipelines that use it stop working at once.

You can also upload a report by hand under Upload a report by hand (up to 5 MB), with the same fields (Cycle name, Build, Branch, Commit, Version, Environment).

Try it:

1. Create a token and copy it.
2. Run curl -X POST "<your CI address>?cycle=Smoke" -H "Authorization: Bearer <token>" --data-binary @report.xml.
3. Open the Cycles tab. The cycle "Smoke" has the results.

Import tests from another tool

Select Import tests, choose a File layout (or Detect from the file) and choose your CSV file. Up to 10 MB and 10,000 rows. Clear Tests recognizes these layouts: Xray, Zephyr Scale, Zephyr Essential, TestRail and Generic CSV.

How to move over:

1. Export your tests to CSV in the old tool. Keep that export as an archive of your old tool. Clear Tests does not delete or change anything there.
   • Xray: use the test export (Issue Key, Test Type, Test Summary, Test Priority, Action, Data, Result, Precondition and so on).
   • Zephyr Scale: export the test cases to CSV (Name, Objective, Precondition, Test Script steps and Expected Result).
   • Zephyr Essential: export the tests to CSV.
   • TestRail: export the cases to CSV (Title, Section, Steps, Expected Result and so on).
   • Any other tool or a spreadsheet: choose Generic CSV. If Clear Tests does not recognize the header row, it shows Choose the columns so that you say which column holds the title, steps, expected results and so on. Only the title is required.
2. Choose the file. Clear Tests checks it in the background and shows the Import plan when it is ready: how many tests will be created, updated, skipped as duplicates, and rows with errors. A small file is ready in seconds; a large one can take a few minutes, and you can keep the page open meanwhile.
3. Read Rows with errors and Duplicates, skipped. The row numbers are spreadsheet rows, as you see them in Excel or Google Sheets, so the header is row 1 and the first test is row 2.
4. Select Apply import. A large file continues in the background. When it ends, the message adds up: created, updated, unchanged, skipped, duplicates and rows with errors. The Tests and Cycles tabs then reload by themselves.

Rules: tests with a key that already exist are updated, not duplicated, so you can import the same file again after fixing it. A test without a key whose title is the same as an existing test in the same folder is skipped as a duplicate. Folders are made from the path in the file. Tests are linked to work items only through the column named below. A column with another name is ignored without a warning (for example, in a Generic CSV a column named Issue Key is not used). Keys that do not exist or that you cannot see are listed and not linked.

Header names are not case sensitive. A cell can hold several keys.

To paste from a spreadsheet instead, use Paste from a spreadsheet: copy the cells from Excel or Google Sheets, including the header row, paste them and select Check pasted rows. Large pastes are checked in the background in the same way.

Export as CSV

There is no file download button. Open Reports > Export, choose Export tests, Export cycle results or Export coverage matrix, and copy the CSV text. The export of tests can be imported again.

Rovo agent

The Clear Tests Rovo agent uses your organisation's Rovo credits, not the Clear Tests AI quota. It can: show test coverage for a work item or a version, list failing tests, summarize a cycle, save test drafts it wrote (saved as Draft), create a cycle and add tests to a cycle. It returns test keys and titles only from projects you can browse, and only counts for other projects.

MCP for coding agents (Preview)

The same actions can be used from MCP clients. This uses a Preview module from Atlassian. The tools act with your own permissions, so you can only reach what you can already reach in Jira.

Custom agents may run create actions, such as creating a cycle, without asking you first, depending on how the agent is set up. The Clear Tests Rovo agent asks first. Every tool acts with your own permissions.

• Custom agents in Rovo Studio: add the tools to your agent with Tools > Add tools > Connected apps > Clear Tests. No extra setup is needed.
• Outside MCP clients (for example a coding assistant): a site or org admin first turns the tools on in Atlassian Administration > Apps > Sites > your site > Connected apps > Clear Tests for Jira. The client then connects to https://mcp.atlassian.com/forge/80334bcb-a631-479b-95c3-f58250debe13, and you approve access when asked.