diff --git a/src/content/docs/project/import-export/import/images/import-source-code/1-select-project-type.png b/src/content/docs/project/import-export/import/images/import-source-code/1-select-project-type.png new file mode 100644 index 00000000..df81e217 Binary files /dev/null and b/src/content/docs/project/import-export/import/images/import-source-code/1-select-project-type.png differ diff --git a/src/content/docs/project/import-export/import/images/import-source-code/2-import-automated-tests.png b/src/content/docs/project/import-export/import/images/import-source-code/2-import-automated-tests.png new file mode 100644 index 00000000..972d8044 Binary files /dev/null and b/src/content/docs/project/import-export/import/images/import-source-code/2-import-automated-tests.png differ diff --git a/src/content/docs/project/import-export/import/images/import-source-code/3-source-code-import-menu.png b/src/content/docs/project/import-export/import/images/import-source-code/3-source-code-import-menu.png new file mode 100644 index 00000000..22a2bfad Binary files /dev/null and b/src/content/docs/project/import-export/import/images/import-source-code/3-source-code-import-menu.png differ diff --git a/src/content/docs/project/import-export/import/images/import-source-code/4-import-tests-terminal.png b/src/content/docs/project/import-export/import/images/import-source-code/4-import-tests-terminal.png new file mode 100644 index 00000000..7c7cdb1d Binary files /dev/null and b/src/content/docs/project/import-export/import/images/import-source-code/4-import-tests-terminal.png differ diff --git a/src/content/docs/project/import-export/import/images/import-source-code/5-1-imported-test.png b/src/content/docs/project/import-export/import/images/import-source-code/5-1-imported-test.png new file mode 100644 index 00000000..a4ef9fb8 Binary files /dev/null and b/src/content/docs/project/import-export/import/images/import-source-code/5-1-imported-test.png differ diff --git a/src/content/docs/project/import-export/import/images/import-source-code/5-imported-test.png b/src/content/docs/project/import-export/import/images/import-source-code/5-imported-test.png new file mode 100644 index 00000000..368bbffd Binary files /dev/null and b/src/content/docs/project/import-export/import/images/import-source-code/5-imported-test.png differ diff --git a/src/content/docs/project/import-export/import/images/import-source-code/6-marked-manual.png b/src/content/docs/project/import-export/import/images/import-source-code/6-marked-manual.png new file mode 100644 index 00000000..2e4fc832 Binary files /dev/null and b/src/content/docs/project/import-export/import/images/import-source-code/6-marked-manual.png differ diff --git a/src/content/docs/project/import-export/import/images/import-source-code/7-additional-settings.png b/src/content/docs/project/import-export/import/images/import-source-code/7-additional-settings.png new file mode 100644 index 00000000..6ed950b2 Binary files /dev/null and b/src/content/docs/project/import-export/import/images/import-source-code/7-additional-settings.png differ diff --git a/src/content/docs/project/import-export/import/images/import-source-code/describe-flatten-flow.png b/src/content/docs/project/import-export/import/images/import-source-code/describe-flatten-flow.png new file mode 100644 index 00000000..cee09bb9 Binary files /dev/null and b/src/content/docs/project/import-export/import/images/import-source-code/describe-flatten-flow.png differ diff --git a/src/content/docs/project/import-export/import/import-tests-from-source-code.md b/src/content/docs/project/import-export/import/import-tests-from-source-code.md index 37c7f539..b359b40b 100644 --- a/src/content/docs/project/import-export/import/import-tests-from-source-code.md +++ b/src/content/docs/project/import-export/import/import-tests-from-source-code.md @@ -15,103 +15,112 @@ head: content: Testomat.io, source code, test import, automated tests, manual tests, test management, repository, GitHub, Jira, BDD, project setup, CI integration, visibility --- -> If you have end-2-end tests, API or unit tests already implemented, you can import them into Testomat.io. +Import end-to-end, API, or unit tests into Testomat.io. Import keeps a large test base manageable. Once imported, you can search across every test, map tests to specifications or Jira tickets, plan new test cases, and get reports. -## Why Do I Need to Import My Tests? +Importing automated tests into Testomat.io makes your work visible to the whole team. It also keeps a large test base manageable. Once imported, you can search across every test, map tests to specifications or Jira tickets, plan new test cases, and get reports. -Automated tests are hidden within the code and, as a rule, this gem is seen only by engineers. Even though the tests play an important role in product management, they are not available to the whole team involved in the project. To bring the visibility of the running tests further on and show what pieces of software are actually covered by tests, you can import your tests into Testomat.io. +## Before import -Moreover, when you have hundreds and thousands of tests on your hands, some things tend to slip through the cracks and end up neglected. For example, you may need to look up certain features and map them with specifications or Jira tickets. In Testomat.io, whenever automated tests are imported, you can search with ease throughout all the tests, plan new test cases, receive reports, and much more! +First, you need to have a project. Follow [Start With Testomat.io](https://docs.testomat.io/getting-started/start-from-scratch/#create-project) to create it. Choose the project type - see [Classical vs BDD](https://docs.testomat.io/project/classical_vs_bdd). -## Create a New Project +This guide covers [Classical projects](https://docs.testomat.io/tutorials/manual-testing-classic). To import a BDD project, see [Import Tests From Cucumber](https://docs.testomat.io/getting-started/import-tests-from-cucumber/#why-do-i-need-to-import-my-tests). -Register at [app.testomat.io](https://app.testomat.io) and activate your user account. Then create a new project. +![Testomat.io - Select type of project](./images/import-source-code/1-select-project-type.png) -![Testomat.io - Create new project](./images/New_qIJOdkr6_2024-07-09.png) +When you create the project, add your **repository URL** (GitHub, GitLab, BitBucket, or self-hosted) and point it at the directory where your tests live. Testomat.io links each test case to its source. -The type of your new project will influence the look of your interface, as well as its intended audience. Choose **BDD Project** if you plan to follow BDD descriptions or use the Cucumber framework in future. If you haven't decided yet, you can start with default **Classical Project**. Depending on your choice, the interface will differ, as follows: - -* Within a **BDD Project**, you will have feature definitions written both in the source code (by engineers) and in Testomatio (by managers and QAs). So you will be able to track and plan Cucumber automation, as well as synchronize the actual feature files with relevant test cases. When a scenario has changed in the system, but has not been updated in the code yet, you will be notified that this certain scenario is out of date. -* Within a **Classical Project**, test cases will be written in free form using markdown. Automated tests will be synced up with test cases, so you will be able to see the test description in one tab and the corresponding test code in another tab. When a description of a test case undergoes changes, you will be notified that a certain test might need to be updated. - -> In this section of the Guide, we discuss the issues concerning Classical Projects. If you need to import a BDD Project, go to the [Import Tests From Cucumber](https://docs.testomat.io/getting-started/import-tests-from-cucumber/#why-do-i-need-to-import-my-tests) section of this guide. - -![Testomat.io - Select type of project](./images/New_hgjKedfJ_2024-07-19.png) - -You can provide a URL of a repository hosted on GitHub, GitLab, BitBucket, as well as of a self-hosted one. Testomat.io will use this URL to navigate you from test cases straight to the source code. Please make sure that the URL is pointing to the *directory where the tests are located*. In the following steps we show in detail how to import tests from that directory. - -> If you fill in the **Repository URL** field, doublecheck that the given path matches the one in the URL repository. For instance, if you have URL: "https://github.com/testomatio/examples/tree/master/playwright/e2e-examples/e2e-tests", you should navigate to "e2e-tests" within your project to import tests. +:::note -Click the **Create** button to start a new project. +Make sure the repository path matches the URL. For example, for `https://github.com/testomatio/examples/tree/master/playwright/e2e-examples/e2e-tests`, navigate to `e2e-tests` in your project to import the tests. -## Import Tests +::: -When your project is created, click the **Import from Source Code** button. +## Import tests -![Testomat.io - Import test cases](./images/New_3EXiVWPT_2024-07-25.png) +Now import the source code into your project. -Or another case: +![Testomat.io - Import test cases](./images/import-source-code/2-import-automated-tests.png) -![Testomat.io - Import automated tests another way](././images/New_GhgayW5f_2024-07-25.png) +1. Go to the **Tests** tab. +2. In the (`...`) menu, click **Import automated tests**. +3. In the **Import Project from Source Code** menu, select: + - your framework. + - your language. + - your operating system. -In the **Import** section, you are asked to pick the framework, programming language and and operating system you are using for testing. +4. Copy the command provided. -![Testomat.io - Copy instructions](./images/New_eUYumU81_2024-07-25.png) +![Testomat.io - Copy instructions](./images/import-source-code/3-source-code-import-menu.png) -> If you don't see the framework you work with in this list - please contact us, and we will do our best to add support for it soon! +Finally, run the command you copied: -Once you have chosen the project parameters, you will be provided with a command that you need to copy and execute in a terminal. Before running this command, please check if your environment matches these requirements: -* If you run tests in NodeJS (JavaScript, TypeScript), you should have NodeJS 10+ and npm to be installed to be able to run this command. -* If you run tests in PHP - you will need PHP > 7.2 and Composer installed. +1. Open a terminal. +2. Go to your tests folder. +3. Run a command. +4. Reopen the project, your tests appear with their folders and files. -Open a terminal, navigate to the tests folder in your project and execute the command. Seeing a report on how many tests were found means that the import command was executed successfully: +![Testomat.io - Execute command in terminal, automated tests found and sent](./images/import-source-code/4-import-tests-terminal.png) -![Testomat.io - Execute command in terminal, automated tests found and sent](./images/New_koBKlQw7_2024-07-26.png) +A report of how many tests were found means the import worked. If you do not see that message, the default settings may not match your setup. The usual causes are a different file-naming format or the wrong import directory. -If you don't see a similar message, this might be because our default settings do not work for you. Please check the command's API change command parameters so it could find tests. The most common issues with import are different file naming format and/or incorrect directory for import. +Every imported test is marked **Automated**. Open a test to see its code and a link to its repository. If the link is wrong, update the repository URL in project settings. -:::note +## Nested describe blocks -All nested suites will be flattened on import for better visibility. So if you have nested `describe` blocks inside the same file they will be imported as separate suites from the file - -::: +Testomat.io keeps one file as one suite. When a file has nested `describe` blocks, they are flattened on import. Each nested block becomes its own suite at the same level, named after its parent. -When the tests are finally imported, reopen the project, and you will see that all tests with their folders and files are shown on Testomat.io. +![Testomat.io - Explain the block](./images/import-source-code/describe-flatten-flow.png) -![Testomat.io - Imported automated tests](./images/New_hcbaJeTv_2024-07-26.png) +This is expected behavior: it shows every test at once, so you do not expand block after block, and it fits the way most projects are organized - one file, one suite. -All imported tests are marked as "Automated" by default. If you click on any of those tests, you will see its code and a link to its repository. Please, check that the link actually points to the corresponding file. Otherwise, you might want to change the repository URL in project settings. +For example, this test file: -![Testomat.io - Automated test source code](./images/New_cIVsD22d_2024-07-26.png) +```js +describe('ActionResult', () => { + it('holds result actions', () => { + // ... + }); -## Import Automated Tests As Manual + describe('isMatchedBy', () => { + it('should match exact URL', () => { + // ... + }); + }); +}); +``` -If you need to import automated tests as manual, just add a tag to the test name in your code and thеn use the same tag in the import settings. In your code, the tag name must begin with the **@** symbol. For instance: `@tagname`. +Imported in Testomat.io like this: -![Testomat.io - Add tag to source code](./images/New_8ZP5jCBP_2024-08-27.png) +``` +ActionResult (action-result.test.ts) + - holds result actions +ActionResult > isMatchedBy (action-result.test.ts) + - should match exact URL +``` -The `manual` name of the tag is used as an example, you can use whatever you like. +The inner `isMatchedBy` block is not nested under `ActionResult` - it becomes a separate suite named `ActionResult > isMatchedBy`. This format stays the same by design, so there is nothing to fix if you see it. -Now, open **Import Project from Source Code** in Testomat.io and specify your project parameters. Just like we did earlier. +![Testomat.io - Imported test in the Tests section in Testomat.io](./images/import-source-code/5-1-imported-test.png) -Before you execute the command, take some additional steps: +## Import automated tests as manual -1. Click **Additional Settings**. -2. Enter a tag name, same as in the code (here without @ symbol). -3. Execute the command in your project and click the **Finish** button. +You need to add the tag to the tests in your own code to import them. In code, the tag starts with **@**, for example `@manual`. -![Testomat.io - Add tag name to import settings](./images/New_DUY4aG6H_2024-08-27.png) +Then you can use the same tag in the import settings. To import an automated test as manual: -On the **Tests** page, the imported tests that have been tagged are listed as manual. +1. Open **Import Project from Source Code**. +2. Set your project parameters. +3. Click **Additional Settings**. +4. Enter the tag name (without the **@**). +5. Run the command in your project. +6. Click **Finish**. -![Testomat.io - Import Automated Tests As Manual](./images/New_QxNiCQPq_2024-08-27.png) +On the **Tests** page, the tagged tests are listed as manual. -## What's Next? +![Testomat.io - Add tag name to import settings](./images/import-source-code/7-additional-settings.png) -Ok, I've just imported my tests successfully, now what? +## Next steps -* **Show your tests to your team**. You must be proud of your work! 🎉 -* **Plan new tests** before automating them. Ask the manager to write test specification within Testomat.io so you could start working on them. -* All new tests will be marked as "manual" unless you import them from code. You can check the number of manual tests that are left, and see the whole range of what is yet to be implemented. -* **Receive run reports** - similarly to Importing tests, you can receive detailed reports on each test execution. Open **Runs** page and follow instructions from there. -* **Add import command to CI** - re-import the tests on each commit to have your project up to date with the source code. +- [Auto-Import](https://docs.testomat.io/project/import-export/auto-import) - re-import on each commit to keep the project in sync with your code. +- [Run Reports](https://docs.testomat.io/project/runs/reports) - get detailed reports on each test execution. +- [Test Plans Overview](https://docs.testomat.io/project/plans) - plan new tests, then automate from there. \ No newline at end of file