Skip to content

Latest commit

 

History

History
40 lines (31 loc) · 8.08 KB

Welcome.md

File metadata and controls

40 lines (31 loc) · 8.08 KB
test_yaml
This should be visibile in {{file_content}} test, but not visible in {{note_content}} test!!!

Welcome!

This Obsidian vault is designed to be a test suite for Obsidian's Shell commands community plugin. It is assumed that you are already familiar with both Obsidian and the Shell commands plugin, and have used them for some time already.

This test suite serves as a standardised tool to make sure that each Shell commands version release is tested in a detailed process, and that the test results are stored in report files for possible later reference. Test reports might be needed for example in bug investigations in order to see if the testing process should be improved.

This Obsidian vault is designed to be stored in a Git repository, and all settings (except appearance.json) are stored in Git. The vault is designed to work with a minimal set of core plugins, which are enabled by default. Core plugins that are not needed, are disabled to keep the UI clean. Other community plugins are not needed to be installed, but you need to install Shell commands community plugin. If a community plugin would bring great advantages to this test suite, then I might consider requiring it to be installed, but this vault should still adhere to easy installation process.

This note offers short guidance on how to get started with testing. I will first introduce you the folder structure of this vault (it aims to be simple), and then point you towards the actual testing process and deeper instructions.

Best supported on Windows and Linux, Mac support in development

The test suite works currently really well on Windows 10 and Linux (particularly Xubuntu 20.04). Mac should be now supported in theory, too, but as I do not own a Macintosh, I cannot be certain. But if the Linux commands work ok on Mac, things should work.

Uses CMD.EXE, PowerShell, Bash and Zsh

On Windows: Most commands are executed using PowerShell Core, but also PowerShell 5 and CMD.EXE are used for some commands. Please have all of these installed if you are testing on Windows!

On Linux and macOS: Most commands are executed using Bash, but also Zsh (Z shell) and Dash are used for some commands. It would be nice if you have these installed if you are testing on Linux or Mac, but if not, you can skip the particular tests that require these. Only Bash is mandatory.

Reports you make and submit will be public

This is a public repository and so your report will be publicly available in the internet, too, if you have decided to make one. If you do not want your report to be published, please contact me, and we can agree what details can be published, or agree to only publish the version information: Operating system name and version, Obsidian version, and Shell commands version, without other information. These three version details are the minimum that are needed in order that it's possible to indicate that the plugin has been tested on a specific operating system.

Folder/file structure

  • _images: Just some installation instructions related images. Not so important.
  • Performed tests: This folder will contain all test report files that you or anyone else creates. Each test run creates just one report file. Part of the test report file's content is created by FINISH TEST shell command.
  • Sandbox: The test suite creates/edits files in this folder. When a test run is to be started, this folder should have only one file: TestResults.md, which should be empty. When the test run finishes, the folder should again only have this one, empty file, nothing else. Also contains caret_position.txt which is used to relocate the caret during Obsidian startup back to where it was last time Obsidian was closed.
  • Templates: Contains Test report.template.md file, which offers a strong structure for all new test report files. Do not touch this file manually! When you are about to create a new test report, use the Open today's daily note command/button in the left side panel! It will copy the file and setup the file name and some other things correctly for you.
  • Test guides: Contains a bit more documentation about certain tests, but currently does not have as much information as could be beneficial to have. You don't need to read the content of this folder at the beginning. More important is to generate your test report file and read instructions there. The report file will also contain links to Test guides in case you like to read more about a specific test.

Get running!

  1. Install Shell commands if it's not yet installed: Hit Ctrl/Cmd + , to open up settings.Go to Community plugins and click Browse button. Type Shell commands to the search field. Select a plugin that has name Shell commands and that is created by Jarkko Linnanvirta. Click Install and remember to click Enable after the installation is completed. You can now close the settings window.
  2. (Optional) Install Red graphite theme from community themes if you want: Hit Ctrl/Cmd + , to open up settings. Go to Appearance, seek for Community themes and click Browse. Type Red graphite (or just red) to the search field and click Use under the theme. I recommend you to set Base theme to Light. Appearance settings are not stored in Git version control, so you can customise them freely, and you can use another theme, too.
  3. Create a new test report file: Execute the BEGIN TEST shell command (or hit Ctrl/Cmd + N hotkey, it's assigned to the same command). This shell command creates a new file in Performed tests folder and opens it in Obsidian.
  4. Perform the test actions: Follow the instructions in your test report file.
    • Each test item is marked with a checkbox. When you have completed the test item's instruction, click the checkbox to mark it done. Tip: use preview mode to be able to click the checkbox - if you are in edit mode, you need to fill the [ ] box with an x: [x].
    • If the plugin does something unexpected, something does not work, or you have questions, edit the report file and add your own notes/questions using == formatting, e.g. ==I'm not sure if this shell command executed correctly== . It will stand out well in the preview mode: ==I'm not sure if this shell command executed correctly==. Put your comment near the test item that it refers to.
    • While working on test items, keep an eye on the [[Sandbox/TestResults]] file. This test suite's shell commands will output their results to that file one at a time, and you need to check if the results look ok or if they have some errors in them. If you are uncertain of a result, you can insert ==a comment/question== into the [[TestResults]] file too, and your comment will eventually become a part of the test report in the finishing phase.
  5. Execute FINISH TEST command: It will move all content from [[Sandbox/TestResults]] to the end of your test report file. This content might look messy and you might have done things in a different order than previous testers. It's fine, the content does not have to look exactly same as in other people's test reports. Mark the checkbox that indicates that you have executed the FINISH TEST command. Executing the command accidentally twice should not do any harm.
  6. Submit your test report file: The best way to submit is by committing it with Git. Do not commit possible changes to any other files, only commit your report file, nothing more, nothing less! It's too easy to accidentally commit e.g. changed settings or accidental edits to these documentation files. If you do not know how to use git, send your report by opening up a new Discussion in the Shell commands repository.