Add error message for invalid domain_ou_path (#92)

Adds a helpful hint to the end of the error message when failing to join
a domain due to an invalid/missing domain_ou_path.

changelogs/fragments/membership-invalid-ou.yml

@@ -0,0 +1,4 @@
+bugfixes:
+  - >-
+    microsoft.ad.membership - Add helpful hint when the failure was due to a missing/invalid ``domain_ou_path``
+    - https://github.com/ansible-collections/microsoft.ad/issues/88

plugins/modules/membership.ps1

@@ -207,7 +207,27 @@ if ($state -eq 'domain') {
                 $joinParams.OUPath = $domainOUPath
             }
 
-            Add-Computer @joinParams
+            try {
+                Add-Computer @joinParams
+            }
+            catch {
+                $failMsg = [string]$_
+
+                # The error if the domain_ou_path does not exist is a bit
+                # vague, we try to catch that specific error type and provide
+                # a more helpful hint to what is wrong. As the exception does
+                # not have an error code to check, we compare the Win32 error
+                # code message with a localized variant for
+                # ERROR_FILE_NOT_FOUND. .NET Framework does not end with .
+                # whereas .NET 5+ does so we use regex to match both patterns.
+                # https://github.com/ansible-collections/microsoft.ad/issues/88
+                $fileNotFound = [System.ComponentModel.Win32Exception]::new(2).Message
+                if ($_.Exception.Message -match ".*$([Regex]::Escape($fileNotFound))\.?`$") {
+                    $failMsg += " Check domain_ou_path is pointing to a valid OU in the target domain."
+                }
+
+                $module.FailJson($failMsg, $_)
+            }
 
             $module.Result.changed = $true
             $module.Result.reboot_required = $true

tests/integration/targets/membership/ansible.cfg

@@ -1,3 +1,4 @@
 [defaults]
 inventory = inventory.yml
 retry_files_enabled = False
+callback_result_format = yaml

tests/integration/targets/membership/tasks/main.yml

@@ -26,6 +26,23 @@
       Get-ADComputer -Filter { Name -ne 'DC' } -Properties DistinguishedName, Name, Enabled |
           Select-Object -Property DistinguishedName, Name, Enabled
 
+- name: join domain invalid OU
+  membership:
+    dns_domain_name: '{{ domain_realm }}'
+    domain_admin_user: '{{ domain_user_upn }}'
+    domain_admin_password: '{{ domain_password }}'
+    domain_ou_path: CN=Invalid,{{ domain_dn_base }}
+    state: domain
+    reboot: true
+  ignore_errors: true
+  register: join_domain_invalid_ou
+
+- name: assert join domain invalid OU
+  assert:
+    that:
+    - join_domain_invalid_ou is failed
+    - join_domain_invalid_ou.msg.endswith('Check domain_ou_path is pointing to a valid OU in the target domain.')
+
 - name: join domain - check mode
   membership:
     dns_domain_name: '{{ domain_realm }}'